familia 2.0.0.pre18 → 2.0.0.pre19

data/lib/familia/errors.rb

@@ -1,19 +1,52 @@
 # lib/familia/errors.rb
 #
 module Familia
+  # Base exception class for all Familia errors
   class Problem < RuntimeError; end
-  class NoIdentifier < Problem; end
-  class NonUniqueKey < Problem; end
 
-  class FieldTypeError < Problem; end
-  class AutoloadError < Problem; end
+  # Base exception class for Redis/persistence-related errors
+  class PersistenceError < Problem; end
 
-  class SerializerError < Problem; end
+  # Base exception class for Horreum models
+  class HorreumError < Problem; end
 
-  # Raised when attempting to start transactions or pipelines on connection types that don't support them
-  class OperationModeError < Problem; end
+  # Raised when an object creation fails (e.g. the identifier
+  # is already in use)
+  class CreationError < HorreumError; end
 
-  class NotDistinguishableError < Problem
+  # Raised when an object lacks a required identifier
+  class NoIdentifier < HorreumError; end
+
+  # Raised when a key is expected to be unique but isn't
+  class NonUniqueKey < PersistenceError; end
+
+  # Raised when watch failed (e.g. key was modified), typically
+  # retry
+  class OptimisticLockError < PersistenceError; end
+
+  # Raised when a field type is invalid or unexpected
+  class FieldTypeError < HorreumError; end
+
+  # Raised when autoloading fails
+  class AutoloadError < HorreumError; end
+
+  # Raised when serialization or deserialization fails
+  class SerializerError < HorreumError; end
+
+  # Raised when attempting to start transactions or pipelines on
+  # connection types that don't support them
+  class OperationModeError < PersistenceError; end
+
+  # Raised when attempting to call a major method like save when
+  # inside a transaction or pipeline
+  class NestedTransactionError < OperationModeError; end
+
+  # Raised when attempting to reference a field that doesn't exist
+  class UnknownFieldError < HorreumError; end
+
+  # Raised when a value cannot be converted to a distinguishable
+  # string representation
+  class NotDistinguishableError < HorreumError
     attr_reader :value
 
     def initialize(value)
@@ -26,7 +59,8 @@ module Familia
     end
   end
 
-  class NotConnected < Problem
+  # Raised when no connection is available for a given URI
+  class NotConnected < PersistenceError
     attr_reader :uri
 
     def initialize(uri)
@@ -39,13 +73,15 @@ module Familia
     end
   end
 
-  # UnsortedSet Familia.connection_provider or use middleware to provide connections.
-  class NoConnectionAvailable < Problem; end
+  # UnsortedSet Familia.connection_provider or use middleware
+  # to provide connections.
+  class NoConnectionAvailable < PersistenceError; end
 
   # Raised when a load method fails to find the requested object
-  class NotFound < Problem; end
+  class NotFound < PersistenceError; end
 
-  # Raised when attempting to refresh an object whose key doesn't exist in the database
+  # Raised when attempting to refresh an object whose key
+  # doesn't exist in the database
   class KeyNotFoundError < NonUniqueKey
     attr_reader :key
 
@@ -59,7 +95,8 @@ module Familia
     end
   end
 
-  # Raised when attempting to create an object that already exists in the database
+  # Raised when attempting to create an object that already
+  # exists in the database
   class RecordExistsError < NonUniqueKey
     attr_reader :key
 

data/lib/familia/features/expiration/extensions.rb

@@ -10,25 +10,23 @@ module Familia
     # with the :expiration feature's implementation.
     #
     # This is a no-op implementation that gets overridden by the :expiration
-    # feature. It accepts an optional default_expiration parameter to maintain
-    # interface compatibility with the overriding implementations.
+    # feature when it is enabled. This allows for calling this method on any
+    # horreum model regardless of the feature status. It accepts an optional
+    # expiration parameter to maintain interface compatibility with
+    # the overriding implementations.
     #
-    # @param default_expiration [Numeric, nil] Time To Live in seconds
+    # @param expiration [Numeric, nil] Time To Live in seconds
     # @return [nil] Always returns nil for the base implementation
     #
     # @note This is a no-op implementation. Classes that need expiration
     #       functionality should include the :expiration feature.
     #
-    # @example Enable expiration feature
-    #   class MyModel < Familia::Horreum
-    #     feature :expiration
-    #     default_expiration 1.hour
-    #   end
+    # @example MyModel.new.update_expiration(expiration: 3600) # => nothing happens
     #
-    def update_expiration(default_expiration: nil)
+    def update_expiration(expiration: nil)
       Familia.ld <<~LOG
         [update_expiration] Expiration feature not enabled for #{self.class}.
-        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+        Key: #{dbkey} Arg: #{expiration} (caller: #{caller(1..1)})
       LOG
       nil
     end

data/lib/familia/features/expiration.rb

@@ -36,7 +36,7 @@ module Familia
     #   session.ttl  # => 1799
     #
     #   # UnsortedSet custom expiration for new objects
-    #   session.update_expiration(default_expiration: 2.hours)
+    #   session.update_expiration(expiration: 2.hours)
     #
     # Class-Level Configuration:
     #
@@ -89,7 +89,7 @@ module Familia
     #
     # Setting expiration to 0 (zero) disables TTL, making data persist indefinitely:
     #
-    #   session.update_expiration(default_expiration: 0)  # No expiration
+    #   session.update_expiration(expiration: 0)  # No expiration
     #
     # TTL Querying:
     #
@@ -115,7 +115,7 @@ module Familia
     #       when 'free'
     #         update_expiration(1.hour)
     #       else
-    #         update_expiration(default_expiration)
+    #         update_expiration(expiration)
     #       end
     #     end
     #   end
@@ -135,10 +135,10 @@ module Familia
     #
     # The feature validates expiration values and raises descriptive errors:
     #
-    #   session.update_expiration(default_expiration: "invalid")
+    #   session.update_expiration(expiration: "invalid")
     #   # => Familia::Problem: Default expiration must be a number
     #
-    #   session.update_expiration(default_expiration: -1)
+    #   session.update_expiration(expiration: -1)
     #   # => Familia::Problem: Default expiration must be non-negative
     #
     # Performance Considerations:
@@ -226,20 +226,20 @@ module Familia
       # after which it will be automatically removed. The method also handles
       # cascading expiration to related data structures when applicable.
       #
-      # @param default_expiration [Numeric, nil] The Time To Live in seconds. If nil,
+      # @param expiration [Numeric, nil] The Time To Live in seconds. If nil,
       #   the default TTL will be used.
       #
       # @return [Boolean] Returns true if the expiration was set successfully,
       #   false otherwise.
       #
       # @example Setting an expiration of one day
-      #   object.update_expiration(default_expiration: 86400)
+      #   object.update_expiration(expiration: 86400)
       #
       # @example Using default expiration
       #   object.update_expiration  # Uses class default_expiration
       #
       # @example Removing expiration (persist indefinitely)
-      #   object.update_expiration(default_expiration: 0)
+      #   object.update_expiration(expiration: 0)
       #
       # @note If default expiration is set to zero, the expiration will be removed,
       #   making the data persist indefinitely.
@@ -247,8 +247,8 @@ module Familia
       # @raise [Familia::Problem] Raises an error if the default expiration is not
       #   a non-negative number.
       #
-      def update_expiration(default_expiration: nil)
-        default_expiration ||= self.default_expiration
+      def update_expiration(expiration: nil)
+        expiration ||= default_expiration
 
         # Handle cascading expiration to related data structures
         if self.class.relations?
@@ -258,8 +258,8 @@ module Familia
             next if definition.opts[:default_expiration].nil?
 
             obj = send(name)
-            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
-            obj.update_expiration(default_expiration: default_expiration)
+            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{expiration}"
+            obj.update_expiration(expiration: expiration)
           end
         end
 
@@ -267,29 +267,29 @@ module Familia
         # It's important to raise exceptions here and not just log warnings. We
         # don't want to silently fail at setting expirations and cause data
         # retention issues (e.g. not removed in a timely fashion).
-        unless default_expiration.is_a?(Numeric)
+        unless expiration.is_a?(Numeric)
           raise Familia::Problem,
-                "Default expiration must be a number (#{default_expiration.class} given for #{self.class})"
+                "Default expiration must be a number (#{expiration.class} given for #{self.class})"
         end
 
-        unless default_expiration >= 0
+        unless expiration >= 0
           raise Familia::Problem,
-                "Default expiration must be non-negative (#{default_expiration} given for #{self.class})"
+                "Default expiration must be non-negative (#{expiration} given for #{self.class})"
         end
 
         # If zero, simply skip setting an expiry for this key. If we were to set
         # 0, Valkey/Redis would drop the key immediately.
-        if default_expiration.zero?
+        if expiration.zero?
           Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
           return true
         end
 
-        Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
+        Familia.ld "[update_expiration] Expires #{dbkey} in #{expiration} seconds"
 
         # The Valkey/Redis' EXPIRE command returns 1 if the timeout was set, 0
         # if key does not exist or the timeout could not be set. Via redis-rb,
         # it's a boolean.
-        expire(default_expiration)
+        expire(expiration)
       end
 
       # Get the remaining time to live for this object's data

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

@@ -32,29 +32,30 @@ module Familia
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index
           # @param index_name [Symbol] Name of the index
-          # @param within [Class, Symbol] Parent class for instance-scoped index (required)
+          # @param within [Class, Symbol] Scope class for instance-scoped index (required)
           # @param query [Boolean] Whether to generate query methods
           def setup(indexed_class:, field:, index_name:, within:, query:)
-            # Multi-index always requires a parent context
-            target_class = within
-            resolved_class = Familia.resolve_class(target_class)
+            # Multi-index always requires a scope context
+            scope_class = within
+            resolved_class = Familia.resolve_class(scope_class)
 
             # Store metadata for this indexing relationship
             indexed_class.indexing_relationships << IndexingRelationship.new(
               field:             field,
-              target_class:      target_class,
+              scope_class:       scope_class,
+              within:            within,
               index_name:        index_name,
               query:            query,
               cardinality:       :multi,
             )
 
             # Always generate the factory method - required by mutation methods
-            if target_class.is_a?(Class)
+            if scope_class.is_a?(Class)
               generate_factory_method(resolved_class, index_name)
             end
 
-            # Generate query methods on the parent class (optional)
-            if query && target_class.is_a?(Class)
+            # Generate query methods on the scope class (optional)
+            if query && scope_class.is_a?(Class)
               generate_query_methods_destination(indexed_class, field, resolved_class, index_name)
             end
 
@@ -62,17 +63,17 @@ module Familia
             generate_mutation_methods_self(indexed_class, field, resolved_class, index_name)
           end
 
-          # Generates the factory method ON THE PARENT CLASS (Company when within: Company):
+          # Generates the factory method ON THE SCOPE CLASS (Company when within: Company):
           # - company.index_name_for(field_value) - DataType factory (always needed)
           #
           # This method is required by mutation methods even when query: false
           #
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :dept_index)
-          def generate_factory_method(target_class, index_name)
-            actual_target_class = Familia.resolve_class(target_class)
+          def generate_factory_method(scope_class, index_name)
+            actual_scope_class = Familia.resolve_class(scope_class)
 
-            actual_target_class.class_eval do
+            actual_scope_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|
@@ -83,21 +84,21 @@ module Familia
             end
           end
 
-          # Generates query methods ON THE PARENT CLASS (Company when within: Company):
+          # Generates query methods ON THE SCOPE CLASS (Company when within: Company):
           # - company.sample_from_department(dept, count=1) - random sampling
           # - company.find_all_by_department(dept) - all objects
           # - company.rebuild_dept_index - rebuild index
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :department)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :dept_index)
-          def generate_query_methods_destination(indexed_class, field, target_class, index_name)
-            # Resolve target class using Familia pattern
-            actual_target_class = Familia.resolve_class(target_class)
+          def generate_query_methods_destination(indexed_class, field, scope_class, index_name)
+            # Resolve scope class using Familia pattern
+            actual_scope_class = Familia.resolve_class(scope_class)
 
             # Generate instance sampling method (e.g., company.sample_from_department)
-            actual_target_class.class_eval do
+            actual_scope_class.class_eval do
 
               define_method(:"sample_from_#{field}") do |field_value, count = 1|
                 index_set = send("#{index_name}_for", field_value) # i.e. UnsortedSet
@@ -133,62 +134,62 @@ module Familia
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :department)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :dept_index)
-          def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
-            target_class_config = target_class.config_name
+          def generate_mutation_methods_self(indexed_class, field, scope_class, index_name)
+            scope_class_config = scope_class.config_name
             indexed_class.class_eval do
-              method_name = :"add_to_#{target_class_config}_#{index_name}"
+              method_name = :"add_to_#{scope_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use helper method on target instance instead of manual instantiation
-                index_set = target_instance.send("#{index_name}_for", field_value)
+                # Use helper method on scope instance instead of manual instantiation
+                index_set = scope_instance.send("#{index_name}_for", field_value)
 
                 # Use UnsortedSet DataType method (no scoring)
                 index_set.add(identifier)
               end
 
-              method_name = :"remove_from_#{target_class_config}_#{index_name}"
+              method_name = :"remove_from_#{scope_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use helper method on target instance instead of manual instantiation
-                index_set = target_instance.send("#{index_name}_for", field_value)
+                # Use helper method on scope instance instead of manual instantiation
+                index_set = scope_instance.send("#{index_name}_for", field_value)
 
                 # Remove using UnsortedSet DataType method
                 index_set.remove(identifier)
               end
 
-              method_name = :"update_in_#{target_class_config}_#{index_name}"
+              method_name = :"update_in_#{scope_class_config}_#{index_name}"
               Familia.ld("[MultiIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance, old_field_value = nil|
-                return unless target_instance
+              define_method(method_name) do |scope_instance, old_field_value = nil|
+                return unless scope_instance
 
                 new_field_value = send(field)
 
                 # Use Familia's transaction method for atomicity with DataType abstraction
-                target_instance.transaction do |_tx|
+                scope_instance.transaction do |_tx|
                   # Remove from old index if provided - use helper method
                   if old_field_value
-                    old_index_set = target_instance.send("#{index_name}_for", old_field_value)
+                    old_index_set = scope_instance.send("#{index_name}_for", old_field_value)
                     old_index_set.remove(identifier)
                   end
 
                   # Add to new index if present - use helper method
                   if new_field_value
-                    new_index_set = target_instance.send("#{index_name}_for", new_field_value)
+                    new_index_set = scope_instance.send("#{index_name}_for", new_field_value)
                     new_index_set.add(identifier)
                   end
                 end