familia 2.0.0.pre5 → 2.0.0.pre6

data/lib/familia/horreum/{definition_methods.rb → subclass/definition.rb}

@@ -1,29 +1,38 @@
-# lib/familia/horreum/definition_methods.rb
+# lib/familia/horreum/subclass/definition.rb
 
 require_relative 'related_fields_management'
+require_relative '../shared/settings'
 
 module Familia
-  VALID_STRATEGIES = %i[raise skip warn overwrite].freeze
+  VALID_STRATEGIES = %i[raise skip ignore warn overwrite].freeze
 
   # Familia::Horreum
   #
   class Horreum
     # Class-level instance variables
     # These are set up as nil initially and populated later
-    @dbclient = nil # TODO
-    @identifier_field = nil
-    @default_expiration = nil
+    #
+    # Connection and database settings
+    @dbclient = nil
     @logical_database = nil
     @uri = nil
-    @suffix = nil
+
+    # Database Key generation settings
     @prefix = nil
-    @fields = nil # []
-    @class_related_fields = nil # {}
-    @related_fields = nil # {}
+    @identifier_field = nil
+    @suffix = nil
+
+    # Fields and relationships
+    @fields = nil
+    @class_related_fields = nil
+    @related_fields = nil
+    @default_expiration = nil
+
+    # Serialization settings
     @dump_method = nil
     @load_method = nil
 
-    # DefinitionMethods: Provides class-level functionality for Horreum
+    # DefinitionMethods: Provides class-level functionality for Horreum subclasses
     #
     # This module is extended into classes that include Familia::Horreum,
     # providing methods for Database operations and object management.
@@ -35,7 +44,7 @@ module Familia
     #
     module DefinitionMethods
       include Familia::Settings
-      include Familia::Horreum::RelatedFieldsManagement
+      include Familia::Horreum::RelatedFieldsManagement # Provides DataType field methods
 
       # Sets or retrieves the unique identifier field for the class.
       #
@@ -86,12 +95,12 @@ module Familia
       #   - Others, depending on features available
       #
       def field(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, category: nil)
-        # Use field type system internally for consistency
-        require_relative '../field_type'
+        # 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'
+                       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
@@ -232,7 +241,7 @@ module Familia
       # @param options [Hash] Field options
       #
       def transient_field(name, **)
-        require_relative '../features/transient_fields/transient_field_type'
+        require_relative '../../features/transient_fields/transient_field_type'
         field_type = TransientFieldType.new(name, **, fast_method: false)
         register_field_type(field_type)
       end
@@ -261,7 +270,7 @@ module Familia
           WARNING
         when :raise
           raise ArgumentError, "Method >>> #{method_name} <<< already defined for #{self}"
-        when :skip
+        when :skip, :ignore
           # Do nothing, skip silently
         end
       end
@@ -279,19 +288,26 @@ module Familia
         end
       end
 
-      # Defines a fast attribute method with a bang (!) suffix for a given
-      # attribute name. Fast attribute methods are used to immediately read or
-      # write attribute values from/to the database. Calling a fast attribute
-      # method has no effect on any of the object's other attributes and does
-      # not trigger a call to update the object's expiration time.
+      # Fast attribute accessor method for immediate DB persistence.
+      #
+      # @param field_name [Symbol, String] the name of the horreum model attribute
+      # @param method_name [Symbol, String] the name of the regular accessor method
+      # @param fast_method_name [Symbol, String] the name of the fast method (must end with '!')
+      # @param on_conflict [Symbol] conflict resolution strategy for method name conflicts
       #
-      # @param [Symbol, String] name the name of the attribute for which the
-      #   fast method is defined.
-      # @return [Object] the current value of the attribute when called without
-      #   arguments.
-      # @raise [ArgumentError] if more than one argument is provided.
-      # @raise [RuntimeError] if an exception occurs during the execution of the
-      #   method.
+      # @return [void]
+      #
+      # @raise [ArgumentError] if fast_method_name doesn't end with '!'
+      #
+      # @note Generated method behavior:
+      #   - Without args: Retrieves current value from Redis
+      #   - With value: Sets and immediately persists to Redis
+      #   - Returns boolean indicating success for writes
+      #   - Bypasses object-level caching and expiration updates
+      #
+      # @example
+      #   # Creates a method like: username!(value = nil)
+      #   define_fast_writer_method(:username, :username, :username!, :raise)
       #
       def define_fast_writer_method(field_name, method_name, fast_method_name, on_conflict)
         raise ArgumentError, 'Must end with !' unless fast_method_name.to_s.end_with?('!')

data/lib/familia/horreum/{management_methods.rb → subclass/management.rb}

@@ -1,4 +1,4 @@
-# lib/familia/horreum/management_methods.rb
+# lib/familia/horreum/subclass/management.rb
 
 require_relative 'related_fields_management'
 
@@ -15,7 +15,7 @@ module Familia
     # * Provides utility methods for working with Database objects
     #
     module ManagementMethods
-      include Familia::Horreum::RelatedFieldsManagement
+      include Familia::Horreum::RelatedFieldsManagement # Provides DataType query methods
 
       # Creates and persists a new instance of the class.
       #
@@ -55,9 +55,7 @@ module Familia
       #
       def create(*, **)
         fobj = new(*, **)
-        raise Familia::Problem, "#{self} already exists: #{fobj.dbkey}" if fobj.exists?
-
-        fobj.save
+        fobj.save_if_not_exists
         fobj
       end
 
@@ -172,8 +170,8 @@ module Familia
       #   User.exists?(123)  # Returns true if user:123:object exists in Redis
       #
       def exists?(identifier, suffix = nil)
+        raise NoIdentifier, "Empty identifier" if identifier.to_s.empty?
         suffix ||= self.suffix
-        return false if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
@@ -234,9 +232,11 @@ module Familia
       # distinction b/c passing in an explicitly nil is how DataType objects
       # at the class level are created without the global default 'object'
       # suffix. See DataType#dbkey "parent_class?" for more details.
+      #
       def dbkey(identifier, suffix = self.suffix)
-        # Familia.ld "[.dbkey] #{identifier} for #{self} (suffix:#{suffix})"
-        raise NoIdentifier, self if identifier.to_s.empty?
+        if identifier.to_s.empty?
+          raise NoIdentifier, "#{self} requires non-empty identifier, got: #{identifier.inspect}"
+        end
 
         identifier &&= identifier.to_s
         Familia.dbkey(prefix, identifier, suffix)
@@ -255,6 +255,7 @@ module Familia
       # Returns the number of dbkeys matching the given filter pattern
       # @param filter [String] dbkey pattern to match (default: '*')
       # @return [Integer] Number of matching keys
+      #
       def matching_keys_count(filter = '*')
         dbclient.keys(dbkey(filter)).compact.size
       end

data/lib/familia/horreum/{related_fields_management.rb → subclass/related_fields_management.rb}

@@ -15,7 +15,7 @@ module Familia
     #
     # Usage:
     #   Include this module in classes that need DataType management
-    #   Call setup_relations_accessors to initialize the feature
+    #   Call setup_related_fields_accessors to initialize the feature
     #
     module RelatedFieldsManagement
       # A practical flag to indicate that a Horreum member has relations,
@@ -23,17 +23,22 @@ module Familia
       @has_relations = nil
 
       def self.included(base)
-        base.extend(ClassMethods)
-        base.setup_relations_accessors
+        base.extend(RelatedFieldsAccessors)
+        base.setup_related_fields_accessors
       end
 
-      module ClassMethods
+      module RelatedFieldsAccessors
         # Sets up all DataType related methods
-        # This method is the core of the metaprogramming logic
+        # This method generates the following for each registered DataType:
         #
-        def setup_relations_accessors
+        # Instance methods: set(), list(), hashkey(), sorted_set(), etc.
+        # Query methods: set?(), list?(), hashkey?(), sorted_set?(), etc.
+        # Collection methods: sets(), lists(), hashkeys(), sorted_sets(), etc.
+        # Class methods: class_set(), class_list(), etc.
+        #
+        def setup_related_fields_accessors
           Familia::DataType.registered_types.each_pair do |kind, klass|
-            Familia.ld "[registered_types] #{kind} => #{klass}"
+            Familia.trace :registered_types, kind, klass, caller(1..1) if Familia.debug?
 
             # Dynamically define instance-level relation methods
             #
@@ -86,11 +91,11 @@ module Familia
           end
         end
       end
-      # End of ClassMethods module
+      # End of RelatedFieldsAccessors module
 
       # Creates an instance-level relation
       def attach_instance_related_field(name, klass, opts)
-        Familia.ld "[#{self}##{name}] Attaching instance-level #{klass} #{opts}"
+        Familia.trace :attach_instance, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, "Name is blank (#{klass})" if name.to_s.empty?
 
         name = name.to_s.to_sym
@@ -115,7 +120,7 @@ module Familia
 
       # Creates a class-level relation
       def attach_class_related_field(name, klass, opts)
-        Familia.ld "[#{self}.#{name}] Attaching class-level #{klass} #{opts}"
+        Familia.trace :attach_class_related_field, "#{name} #{klass}", opts, caller(1..1) if Familia.debug?
         raise ArgumentError, 'Name is blank (klass)' if name.to_s.empty?
 
         name = name.to_s.to_sym

data/lib/familia/horreum.rb

@@ -1,5 +1,10 @@
 # lib/familia/horreum.rb
 
+require_relative 'horreum/subclass/definition'
+require_relative 'horreum/subclass/management'
+require_relative 'horreum/shared/settings'
+require_relative 'horreum/core'
+
 module Familia
   #
   # Horreum: A module for managing Redis-based object storage and relationships
@@ -23,6 +28,8 @@ module Familia
   #
   class Horreum
     include Familia::Base
+    include Familia::Horreum::Core
+    include Familia::Horreum::Settings
 
     # Singleton Class Context
     #
@@ -62,13 +69,14 @@ module Familia
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
         Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
-        member.extend(DefinitionMethods)
-        member.extend(ManagementMethods)
-        member.extend(Connection)
-        member.extend(Features)
 
-        # Tracks all the classes/modules that include Familia. It's
-        # 10pm, do you know where you Familia members are?
+        # Class-level functionality extensions:
+        member.extend(Familia::Horreum::DefinitionMethods)    # field(), identifier_field(), dbkey()
+        member.extend(Familia::Horreum::ManagementMethods)    # create(), find(), destroy!()
+        member.extend(Familia::Horreum::Connection)           # dbclient, connection management
+        member.extend(Familia::Features)             # feature() method for optional modules
+
+        # Track all classes that inherit from Horreum
         Familia.members << member
         super
       end
@@ -84,7 +92,7 @@ module Familia
     #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
-      Familia.ld "[Horreum] Initializing #{self.class}"
+      Familia.trace :INITIALIZE, dbclient, "Initializing #{self.class}", caller(1..1) if Familia.debug?
       initialize_relatives
 
       # No longer auto-create a key field - the identifier method will
@@ -123,7 +131,7 @@ module Familia
       elsif args.any?
         initialize_with_positional_args(*args)
       else
-        Familia.ld "[Horreum] #{self.class} initialized with no arguments"
+      Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
         # Default values are intentionally NOT set here to:
         # - Maintain Database memory efficiency (only store non-nil values)
         # - Avoid conflicts with nil-skipping serialization logic
@@ -158,7 +166,7 @@ module Familia
       self.class.related_fields.each_pair do |name, data_type_definition|
         klass = data_type_definition.klass
         opts = data_type_definition.opts
-        Familia.ld "[#{self.class}] initialize_relatives #{name} => #{klass} #{opts.keys}"
+        Familia.trace :INITIALIZE_RELATIVES, dbclient, "#{name} => #{klass} #{opts.keys}", caller(1..1) if Familia.debug?
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
         # automatically. This is what determines the dbkey for DataType
@@ -310,11 +318,3 @@ module Familia
     end
   end
 end
-
-require_relative 'horreum/definition_methods'
-require_relative 'horreum/management_methods'
-require_relative 'horreum/database_commands'
-require_relative 'horreum/connection'
-require_relative 'horreum/serialization'
-require_relative 'horreum/settings'
-require_relative 'horreum/utils'

data/lib/familia/version.rb

@@ -3,6 +3,6 @@
 module Familia
   # Version information for the Familia
   unless defined?(Familia::VERSION)
-    VERSION = '2.0.0.pre5'
+    VERSION = '2.0.0.pre6'
   end
 end

data/lib/familia.rb

@@ -73,9 +73,9 @@ module Familia
   require_relative 'familia/utils'
 
   extend SecureIdentifier
-  extend Logging
   extend Connection
   extend Settings
+  extend Logging
   extend Utils
 end
 

data/try/core/create_method_try.rb

@@ -0,0 +1,240 @@
+# try/core/create_method_try.rb
+#
+# Comprehensive test coverage for the create method
+# Tests the correct exception type and error message handling
+
+require_relative '../helpers/test_helpers'
+
+# Test class for create method behavior
+class CreateTestModel < Familia::Horreum
+  identifier_field :id
+  field :id
+  field :name
+  field :value
+end
+
+# Clean up any existing test data
+cleanup_keys = []
+begin
+  existing_test_keys = Familia.dbclient.keys('createtestmodel:*')
+  cleanup_keys.concat(existing_test_keys)
+  Familia.dbclient.del(*existing_test_keys) if existing_test_keys.any?
+rescue => e
+  # Ignore cleanup errors
+end
+
+@test_id_counter = 0
+def next_test_id
+  @test_id_counter += 1
+  "create-test-#{Time.now.to_i}-#{@test_id_counter}"
+end
+
+# =============================================
+# 1. Basic create method functionality
+# =============================================
+
+## create method successfully creates new object
+@test_id = next_test_id
+@created_obj = CreateTestModel.create(id: @test_id, name: 'Created Object', value: 'test_value')
+[@created_obj.class, @created_obj.exists?, @created_obj.name]
+#=> [CreateTestModel, true, 'Created Object']
+
+## create method returns the created object
+@created_obj.is_a?(CreateTestModel)
+#=> true
+
+## create method persists object fields
+@created_obj.refresh!
+[@created_obj.name, @created_obj.value]
+#=> ['Created Object', 'test_value']
+
+# =============================================
+# 2. Duplicate creation error handling
+# =============================================
+
+## create method raises RecordExistsError for duplicate
+begin
+  CreateTestModel.create(id: @test_id, name: 'Duplicate Attempt')
+  false  # Should not reach here
+rescue => e
+  e.class
+end
+#=> Familia::RecordExistsError
+
+## RecordExistsError includes the dbkey in the message
+begin
+  CreateTestModel.create(id: @test_id, name: 'Another Duplicate')
+  false  # Should not reach here
+rescue Familia::RecordExistsError => e
+  expected_dbkey = "createtestmodel:#{@test_id}:object"
+  e.message.include?(expected_dbkey)
+end
+#=> true
+
+## RecordExistsError message follows consistent format
+begin
+  CreateTestModel.create(id: @test_id, name: 'Yet Another Duplicate')
+  false  # Should not reach here
+rescue Familia::RecordExistsError => e
+  e.message.start_with?('Key already exists:')
+end
+#=> true
+
+## RecordExistsError exposes key property for programmatic access
+@final_test_id = next_test_id
+CreateTestModel.create(id: @final_test_id, name: 'Setup for Key Test')
+
+begin
+  CreateTestModel.create(id: @final_test_id, name: 'Key Test Duplicate')
+  false  # Should not reach here
+rescue Familia::RecordExistsError => e
+  # Key should be accessible and contain the identifier
+  [e.respond_to?(:key), e.key.include?(@final_test_id)]
+end
+#=> [true, true]
+
+# =============================================
+# 3. Edge cases and error conditions
+# =============================================
+
+## create with empty identifier raises NoIdentifier error
+CreateTestModel.create(id: '')
+#=!> Familia::NoIdentifier
+
+## create with nil identifier raises NoIdentifier error
+CreateTestModel.create(id: nil)
+#=!> Familia::NoIdentifier
+
+## create with only some fields set
+@partial_id = next_test_id
+@partial_obj = CreateTestModel.create(id: @partial_id, name: 'Partial Object')
+[@partial_obj.exists?, @partial_obj.name, @partial_obj.value]
+#=> [true, 'Partial Object', nil]
+
+## create with no additional fields (only identifier)
+@minimal_id = next_test_id
+@minimal_obj = CreateTestModel.create(id: @minimal_id)
+[@minimal_obj.exists?, @minimal_obj.id]
+#=> [true, @minimal_id]
+
+# =============================================
+# 4. Concurrency and transaction behavior
+# =============================================
+
+## create is atomic - no partial state on failure
+@concurrent_id = next_test_id
+@first_obj = CreateTestModel.create(id: @concurrent_id, name: 'First')
+
+# Verify first object exists
+first_exists = @first_obj.exists?
+
+# Attempt to create duplicate should not affect existing object
+begin
+  CreateTestModel.create(id: @concurrent_id, name: 'Concurrent Attempt')
+  false  # Should not reach here
+rescue Familia::RecordExistsError
+  # Original object should be unchanged
+  @first_obj.refresh!
+  @first_obj.name == 'First'
+end
+#=> true
+
+## create failure doesn't leave partial data
+before_failed_create = Familia.dbclient.keys("createtestmodel:#{@concurrent_id}:*").length
+begin
+  CreateTestModel.create(id: @concurrent_id, name: 'Should Fail')
+rescue Familia::RecordExistsError
+  # Should not create any additional keys
+  after_failed_create = Familia.dbclient.keys("createtestmodel:#{@concurrent_id}:*").length
+  after_failed_create == before_failed_create
+end
+#=> true
+
+# =============================================
+# 5. Consistency with save_if_not_exists
+# =============================================
+
+## Both create and save_if_not_exists raise same error type for duplicates
+@consistency_id = next_test_id
+@consistency_obj = CreateTestModel.create(id: @consistency_id, name: 'Consistency Test')
+
+# Test create raises RecordExistsError
+create_error_class = begin
+  CreateTestModel.create(id: @consistency_id, name: 'Create Duplicate')
+  nil
+rescue => e
+  e.class
+end
+
+# Test save_if_not_exists raises RecordExistsError
+sine_error_class = begin
+  duplicate_obj = CreateTestModel.new(id: @consistency_id, name: 'SINE Duplicate')
+  duplicate_obj.save_if_not_exists
+  nil
+rescue => e
+  e.class
+end
+
+[create_error_class, sine_error_class]
+#=> [Familia::RecordExistsError, Familia::RecordExistsError]
+
+## Both methods have similar error message patterns
+@error_comparison_id = next_test_id
+CreateTestModel.create(id: @error_comparison_id, name: 'Error Comparison')
+
+create_error_msg = begin
+  CreateTestModel.create(id: @error_comparison_id, name: 'Create Error')
+  nil
+rescue => e
+  e.message
+end
+
+sine_error_msg = begin
+  CreateTestModel.new(id: @error_comparison_id, name: 'SINE Error').save_if_not_exists
+  nil
+rescue => e
+  e.message
+end
+
+# Both should reference the same key concept
+[create_error_msg.include?('already exists'), sine_error_msg.include?('already exists')]
+#=> [true, true]
+
+# =============================================
+# 6. Integration with different field types
+# =============================================
+
+## create works with complex field values
+@complex_id = next_test_id
+@complex_obj = CreateTestModel.create(
+  id: @complex_id,
+  name: 'Complex Object',
+  value: { nested: 'data', array: [1, 2, 3] }
+)
+[@complex_obj.exists?, @complex_obj.value[:nested]]
+#=> [true, 'data']
+
+# =============================================
+# 7. Class vs instance method consistency
+# =============================================
+
+## Class.create and instance.save_if_not_exists have consistent existence checking
+@consistency_check_id = next_test_id
+
+# Create via class method
+@class_created = CreateTestModel.create(id: @consistency_check_id, name: 'Class Created')
+
+# Both class and instance methods should see the object as existing
+class_sees_exists = CreateTestModel.exists?(@consistency_check_id)
+instance_sees_exists = @class_created.exists?
+
+[class_sees_exists, instance_sees_exists]
+#=> [true, true]
+
+# =============================================
+# Cleanup
+# =============================================
+
+# Clean up all test data
+test_keys = Familia.dbclient.keys('createtestmodel:*')
+Familia.dbclient.del(*test_keys) if test_keys.any?