familia 2.0.0.pre17 → 2.0.0.pre18

data/lib/familia/features/autoloader.rb

@@ -28,7 +28,9 @@ module Familia::Features
       ]
 
       # Ensure the Features module exists within the base module
-      base.const_set(:Features, Module.new) unless base.const_defined?(:Features) || config_name.eql?('features')
+      unless base.const_defined?(:Features) || config_name.eql?('features')
+        base.const_set(:Features, Module.new)
+      end
 
       # Use the shared autoload_files method
       autoload_files(dir_patterns, log_prefix: "Autoloader[#{config_name}]")

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -29,8 +29,10 @@ module Familia
             # Already concealed, store as-is
             instance_variable_set(:"@#{field_name}", value)
           elsif field_type.encrypted_json?(value)
-            # Already encrypted JSON from database - wrap in ConcealedString without re-encrypting
-            concealed = ConcealedString.new(value, self, field_type)
+            # Already encrypted (JSON string or Hash from database) - wrap in ConcealedString without re-encrypting
+            # Convert Hash back to JSON string if needed (v2.0 deserialization returns Hash)
+            encrypted_string = value.is_a?(Hash) ? Familia::JsonSerializer.dump(value) : value
+            concealed = ConcealedString.new(encrypted_string, self, field_type)
             instance_variable_set(:"@#{field_name}", concealed)
           else
             # Encrypt plaintext and wrap in ConcealedString
@@ -138,7 +140,13 @@ module Familia
 
     # Check if a string looks like encrypted JSON data
     def encrypted_json?(data)
-      Familia::Encryption::EncryptedData.valid?(data)
+      # Support both JSON strings (legacy) and Hashes (v2.0 deserialization)
+      if data.is_a?(Hash)
+        required_keys = %w[algorithm nonce ciphertext auth_tag key_version]
+        required_keys.all? { |key| data.key?(key) || data.key?(key.to_sym) }
+      else
+        Familia::Encryption::EncryptedData.valid?(data)
+      end
     end
 
     private

data/lib/familia/features/relationships/indexing/multi_index_generators.rb

@@ -75,7 +75,7 @@ module Familia
             actual_target_class.class_eval do
               # Helper method to get index set for a specific field value
               # This acts as a factory for field-value-specific DataTypes
-              define_method("#{index_name}_for") do |field_value|
+              define_method(:"#{index_name}_for") do |field_value|
                 # Return properly managed DataType instance with parameterized key
                 index_key = "#{index_name}:#{field_value}"
                 Familia::UnsortedSet.new(index_key, parent: self)
@@ -99,26 +99,26 @@ module Familia
             # Generate instance sampling method (e.g., company.sample_from_department)
             actual_target_class.class_eval do
 
-              define_method("sample_from_#{field}") do |field_value, count = 1|
+              define_method(:"sample_from_#{field}") do |field_value, count = 1|
                 index_set = send("#{index_name}_for", field_value) # i.e. UnsortedSet
 
                 # Get random members efficiently (O(1) via SRANDMEMBER with count)
                 # Returns array even for count=1 for consistent API
                 index_set.sample(count).map do |id|
-                  indexed_class.new(index_set.deserialize_value(id))
+                  indexed_class.find_by_identifier(id)
                 end
               end
 
               # Generate bulk query method (e.g., company.find_all_by_department)
-              define_method("find_all_by_#{field}") do |field_value|
+              define_method(:"find_all_by_#{field}") do |field_value|
                 index_set = send("#{index_name}_for", field_value) # i.e. UnsortedSet
 
                 # Get all members from set
-                index_set.members.map { |id| indexed_class.new(id) }
+                index_set.members.map { |id| indexed_class.find_by_identifier(id) }
               end
 
               # Generate method to rebuild the index for this parent instance
-              define_method("rebuild_#{index_name}") do
+              define_method(:"rebuild_#{index_name}") do
                 # This would need to be implemented based on how you track which
                 # objects belong to this parent instance
                 # For now, just a placeholder
@@ -138,7 +138,7 @@ module Familia
           def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
             target_class_config = target_class.config_name
             indexed_class.class_eval do
-              method_name = "add_to_#{target_class_config}_#{index_name}"
+              method_name = :"add_to_#{target_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance|
@@ -154,7 +154,7 @@ module Familia
                 index_set.add(identifier)
               end
 
-              method_name = "remove_from_#{target_class_config}_#{index_name}"
+              method_name = :"remove_from_#{target_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance|
@@ -170,7 +170,7 @@ module Familia
                 index_set.remove(identifier)
               end
 
-              method_name = "update_in_#{target_class_config}_#{index_name}"
+              method_name = :"update_in_#{target_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance, old_field_value = nil|

data/lib/familia/features/relationships/indexing/unique_index_generators.rb

@@ -104,36 +104,42 @@ module Familia
 
             # Generate instance query method (e.g., company.find_by_badge_number)
             actual_target_class.class_eval do
-              define_method("find_by_#{field}") do |field_value|
+              define_method(:"find_by_#{field}") do |provided_value|
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
 
-                # Get the identifier from the hash
-                object_id = index_hash[field_value.to_s]
-                return nil unless object_id
+                # Get the identifier from the hash using .get method.
+                # We use .get instead of [] because it's part of the standard interface
+                # common across all DataType classes (List, UnsortedSet, SortedSet, HashKey).
+                # While unique indexes always use HashKey, using .get maintains consistency
+                # with the broader DataType API patterns used throughout Familia.
+                record_id = index_hash.get(provided_value)
+                return nil unless record_id
 
-                indexed_class.new(object_id)
+                indexed_class.find_by_identifier(record_id)
               end
 
               # Generate bulk query method (e.g., company.find_all_by_badge_number)
-              define_method("find_all_by_#{field}") do |field_values|
-                field_values = Array(field_values)
-                return [] if field_values.empty?
+              define_method(:"find_all_by_#{field}") do |provided_ids|
+                provided_ids = Array(provided_ids)
+                return [] if provided_ids.empty?
 
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
 
                 # Get all identifiers from the hash
-                object_ids = index_hash.values_at(*field_values.map(&:to_s))
+                record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
                 # Filter out nil values and instantiate objects
-                object_ids.compact.map { |object_id| indexed_class.new(object_id) }
+                record_ids.compact.map { |record_id|
+                  indexed_class.find_by_identifier(record_id)
+                }
               end
 
               # Accessor method already created by ensure_index_field above
               # No need to manually define it here
 
               # Generate method to rebuild the unique index for this parent instance
-              define_method("rebuild_#{index_name}") do
+              define_method(:"rebuild_#{index_name}") do
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
 
@@ -160,7 +166,7 @@ module Familia
           def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
             target_class_config = target_class.config_name
             indexed_class.class_eval do
-              method_name = "add_to_#{target_class_config}_#{index_name}"
+              method_name = :"add_to_#{target_class_config}_#{index_name}"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance|
@@ -176,7 +182,7 @@ module Familia
                 index_hash[field_value.to_s] = identifier
               end
 
-              method_name = "remove_from_#{target_class_config}_#{index_name}"
+              method_name = :"remove_from_#{target_class_config}_#{index_name}"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance|
@@ -192,7 +198,7 @@ module Familia
                 index_hash.remove(field_value.to_s)
               end
 
-              method_name = "update_in_#{target_class_config}_#{index_name}"
+              method_name = :"update_in_#{target_class_config}_#{index_name}"
               Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
 
               define_method(method_name) do |target_instance, old_field_value = nil|
@@ -222,31 +228,39 @@ module Familia
           # - Employee.email_index
           # - Employee.rebuild_email_index
           def generate_query_methods_class(field, index_name, indexed_class)
-            indexed_class.define_singleton_method("find_by_#{field}") do |field_value|
+            indexed_class.define_singleton_method(:"find_by_#{field}") do |provided_id|
               index_hash = send(index_name) # Access the class-level hashkey DataType
-              object_id = index_hash[field_value.to_s]
 
-              return nil unless object_id
+              # Get the identifier from the hash using .get method.
+              # We use .get instead of [] because it's part of the standard interface
+              # common across all DataType classes (List, UnsortedSet, SortedSet, HashKey).
+              # While unique indexes always use HashKey, using .get maintains consistency
+              # with the broader DataType API patterns used throughout Familia.
+              record_id = index_hash.get(provided_id)
 
-              new(object_id)
+              return nil unless record_id
+
+              indexed_class.find_by_identifier(record_id)
             end
 
             # Generate class-level bulk query method
-            indexed_class.define_singleton_method("find_all_by_#{field}") do |field_values|
-              field_values = Array(field_values)
-              return [] if field_values.empty?
+            indexed_class.define_singleton_method(:"find_all_by_#{field}") do |provided_ids|
+              provided_ids = Array(provided_ids)
+              return [] if provided_ids.empty?
 
               index_hash = send(index_name) # Access the class-level hashkey DataType
-              object_ids = index_hash.values_at(*field_values.map(&:to_s))
+              record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
               # Filter out nil values and instantiate objects
-              object_ids.compact.map { |object_id| new(object_id) }
+              record_ids.compact.map { |record_id|
+                indexed_class.find_by_identifier(record_id)
+              }
             end
 
             # The index accessor method is already created by the class_hashkey declaration
             # No need to manually create it - Horreum handles this automatically
 
             # Generate method to rebuild the class-level index
-            indexed_class.define_singleton_method("rebuild_#{index_name}") do
+            indexed_class.define_singleton_method(:"rebuild_#{index_name}") do
               index_hash = send(index_name) # Access the class-level hashkey DataType
 
               # Clear existing index using DataType method
@@ -265,7 +279,7 @@ module Familia
           # - employee.update_in_class_email_index(old_email)
           def generate_mutation_methods_class(field, index_name, indexed_class)
             indexed_class.class_eval do
-              define_method("add_to_class_#{index_name}") do
+              define_method(:"add_to_class_#{index_name}") do
                 index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
                 field_value = send(field)
 
@@ -274,7 +288,7 @@ module Familia
                 index_hash[field_value.to_s] = identifier
               end
 
-              define_method("remove_from_class_#{index_name}") do
+              define_method(:"remove_from_class_#{index_name}") do
                 index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
                 field_value = send(field)
 
@@ -283,7 +297,7 @@ module Familia
                 index_hash.remove(field_value.to_s)
               end
 
-              define_method("update_in_class_#{index_name}") do |old_field_value = nil|
+              define_method(:"update_in_class_#{index_name}") do |old_field_value = nil|
                 new_field_value = send(field)
 
                 # Use class-level transaction for atomicity with DataType abstraction

data/lib/familia/features/safe_dump.rb

@@ -1,9 +1,8 @@
 # lib/familia/features/safe_dump.rb
 
 #
-#   Class instance variables are used here for feature configuration
-#   (e.g., @dump_method, @load_method). These are set once and not mutated
-#   at runtime, so thread safety is not a concern for this feature.
+# Class instance variables are used here for configuration. These are set
+# once at loadtime and not mutated, so thread safety is not an issue here.
 #
 module Familia
   module Features

data/lib/familia/horreum/database_commands.rb

@@ -121,7 +121,7 @@ module Familia
       end
 
       def hmset(hsh = {})
-        hsh ||= to_h
+        hsh ||= to_h_for_storage
         Familia.trace :HMSET, nil, hsh if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end

data/lib/familia/horreum/definition.rb

@@ -2,6 +2,8 @@
 
 require_relative 'settings'
 
+require_relative '../field_type'
+
 module Familia
   VALID_STRATEGIES = %i[raise skip ignore warn overwrite].freeze
 
@@ -27,10 +29,6 @@ module Familia
     @related_fields = nil
     @default_expiration = nil
 
-    # Serialization settings
-    @dump_method = nil
-    @load_method = nil
-
     # Field groups
     @field_groups = nil
     @current_field_group = nil
@@ -171,30 +169,9 @@ module Familia
       #   - :skip - skip definition if method exists
       #   - :warn - warn but proceed (may overwrite)
       #   - :ignore - proceed silently (may overwrite)
-      # @param category [Symbol, nil] field category for special handling:
-      #   - nil - regular field (default)
-      #   - :encrypted - field contains encrypted data
-      #   - :transient - field is not persisted
-      #   - Others, depending on features available
-      #
-      def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
-        # Use field type system for consistency
-        require_relative '../field_type'
-
-        # Create appropriate field type based on category
-        field_type = if category == :transient
-          require_relative '../features/transient_fields/transient_field_type'
-          TransientFieldType.new(name, as: as, fast_method: false, on_conflict: on_conflict)
-        else
-          # For regular fields and other categories, create custom field type with category override
-          custom_field_type = Class.new(FieldType) do
-            define_method :category do
-              category || :field
-            end
-          end
-          custom_field_type.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
-        end
-
+      #
+      def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise)
+        field_type = FieldType.new(name, as: as, fast_method: fast_method, on_conflict: on_conflict)
         register_field_type(field_type)
       end
 
@@ -256,14 +233,6 @@ module Familia
         @has_related_fields ||= false
       end
 
-      def dump_method
-        @dump_method || :to_json # Familia.dump_method
-      end
-
-      def load_method
-        @load_method || :from_json # Familia.load_method
-      end
-
       # Storage for field type instances
       def field_types
         @field_types ||= {}
@@ -506,7 +475,7 @@ module Familia
 
               # Convert the provided value to a format suitable for Database storage.
               prepared = serialize_value(val)
-              Familia.ld "[.define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+              Familia.ld "[define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
 
               # Use the existing accessor method to set the attribute value.
               send :"#{method_name}=", val

data/lib/familia/horreum/management.rb

@@ -125,15 +125,15 @@ module Familia
       #   User.find_by_key("user:123")  # Returns a User instance if it exists,
       #   nil otherwise
       #
-      def find_by_key(objkey)
+      def find_by_dbkey(objkey)
         raise ArgumentError, 'Empty key' if objkey.to_s.empty?
 
         # We use a lower-level method here b/c we're working with the
         # full key and not just the identifier.
         does_exist = dbclient.exists(objkey).positive?
 
-        Familia.ld "[.find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
-        Familia.trace :FROM_KEY, nil, objkey if Familia.debug?
+        Familia.ld "[find_by_key] #{self} from key #{objkey} (exists: #{does_exist})"
+        Familia.trace :FIND_BY_DBKEY_KEY, nil, objkey
 
         # This is the reason for calling exists first. We want to definitively
         # and without any ambiguity know if the object exists in the database. If it
@@ -143,11 +143,16 @@ module Familia
         return unless does_exist
 
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
-        Familia.trace :FROM_KEY2, nil, "#{objkey}: #{obj.inspect}" if Familia.debug?
-
-        new(**obj)
+        Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{objkey}: #{obj.inspect}"
+
+        # Create instance and deserialize fields using existing helper method
+        # This avoids duplicating deserialization logic and keeps field-by-field processing
+        instance = allocate
+        instance.send(:initialize_relatives)
+        instance.send(:initialize_with_keyword_args_deserialize_value, **obj)
+        instance
       end
-      alias from_dbkey find_by_key # deprecated
+      alias find_by_key find_by_dbkey
 
       # Retrieves and instantiates an object from Database using its identifier.
       #
@@ -168,19 +173,19 @@ module Familia
       # @example
       #   User.find_by_id(123)  # Equivalent to User.find_by_key("user:123:object")
       #
-      def find_by_id(identifier, suffix = nil)
+      def find_by_identifier(identifier, suffix = nil)
         suffix ||= self.suffix
         return nil if identifier.to_s.empty?
 
         objkey = dbkey(identifier, suffix)
 
-        Familia.ld "[.find_by_id] #{self} from key #{objkey})"
+        Familia.ld "[find_by_id] #{self} from key #{objkey})"
         Familia.trace :FIND_BY_ID, nil, objkey if Familia.debug?
-        find_by_key objkey
+        find_by_dbkey objkey
       end
+      alias find_by_id find_by_identifier
       alias find find_by_id
-      alias load find_by_id # deprecated
-      alias from_identifier find_by_id # deprecated
+      alias load find_by_id
 
       # Checks if an object with the given identifier exists in the database.
       #

data/lib/familia/horreum/persistence.rb

@@ -354,7 +354,7 @@ module Familia
         # their uninitialized state during refresh operations
         reset_transient_fields!
 
-        optimistic_refresh(**fields)
+        naive_refresh(**fields)
       end
 
       # Refreshes object state from the DB and returns self for method chaining.