familia 2.0.0.pre4 → 2.0.0.pre5

data/lib/familia/field_type.rb

@@ -0,0 +1,270 @@
+# lib/familia/field_type.rb
+
+module Familia
+  # Base class for all field types in Familia
+  #
+  # Field types encapsulate the behavior for different kinds of fields,
+  # including how their getter/setter methods are defined and how values
+  # are serialized/deserialized.
+  #
+  # @example Creating a custom field type
+  #   class TimestampFieldType < Familia::FieldType
+  #     def define_setter(klass)
+  #       field_name = @name
+  #       klass.define_method :"#{@method_name}=" do |value|
+  #         timestamp = value.is_a?(Time) ? value.to_i : value
+  #         instance_variable_set(:"@#{field_name}", timestamp)
+  #       end
+  #     end
+  #
+  #     def define_getter(klass)
+  #       field_name = @name
+  #       klass.define_method @method_name do
+  #         timestamp = instance_variable_get(:"@#{field_name}")
+  #         timestamp ? Time.at(timestamp) : nil
+  #       end
+  #     end
+  #   end
+  #
+  class FieldType
+    attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict
+
+    # Initialize a new field type
+    #
+    # @param name [Symbol] The field name
+    # @param as [Symbol, String, false] The method name (defaults to field name)
+    #   If false, no accessor methods are created
+    # @param fast_method [Symbol, String, false] The fast method name
+    #   (defaults to "#{name}!"). If false, no fast method is created
+    # @param on_conflict [Symbol] Conflict resolution strategy when method
+    #   already exists (:raise, :skip, :warn, :overwrite)
+    # @param options [Hash] Additional options for the field type
+    #
+    def initialize(name, as: name, fast_method: :"#{name}!", on_conflict: :raise, **options)
+      @name = name.to_sym
+      @method_name = as == false ? nil : as.to_sym
+      @fast_method_name = fast_method == false ? nil : fast_method&.to_sym
+
+      # Validate fast method name format
+      if @fast_method_name && !@fast_method_name.to_s.end_with?('!')
+        raise ArgumentError, "Fast method name must end with '!' (got: #{@fast_method_name})"
+      end
+
+      @on_conflict = on_conflict
+      @options = options
+    end
+
+    # Install this field type on a class
+    #
+    # This method defines all necessary methods on the target class
+    # and registers the field type for later reference.
+    #
+    # @param klass [Class] The class to install this field type on
+    #
+    def install(klass)
+      if @method_name
+        # For skip strategy, check for any method conflicts first
+        if @on_conflict == :skip
+          has_getter_conflict = klass.method_defined?(@method_name) || klass.private_method_defined?(@method_name)
+          has_setter_conflict = klass.method_defined?(:"#{@method_name}=") || klass.private_method_defined?(:"#{@method_name}=")
+
+          # If either getter or setter conflicts, skip the whole field
+          return if has_getter_conflict || has_setter_conflict
+        end
+
+        define_getter(klass)
+        define_setter(klass)
+      end
+
+      define_fast_writer(klass) if @fast_method_name
+    end
+
+    # Define the getter method on the target class
+    #
+    # Subclasses can override this to customize getter behavior.
+    # The default implementation creates a simple attr_reader equivalent.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_getter(klass)
+      field_name = @name
+      method_name = @method_name
+
+      handle_method_conflict(klass, method_name) do
+        klass.define_method method_name do
+          instance_variable_get(:"@#{field_name}")
+        end
+      end
+    end
+
+    # Define the setter method on the target class
+    #
+    # Subclasses can override this to customize setter behavior.
+    # The default implementation creates a simple attr_writer equivalent.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_setter(klass)
+      field_name = @name
+      method_name = @method_name
+
+      handle_method_conflict(klass, :"#{method_name}=") do
+        klass.define_method :"#{method_name}=" do |value|
+          instance_variable_set(:"@#{field_name}", value)
+        end
+      end
+    end
+
+    # Define the fast writer method on the target class
+    #
+    # Fast methods provide direct database access for immediate persistence.
+    # Subclasses can override this to customize fast method behavior.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_fast_writer(klass)
+      return unless @fast_method_name&.to_s&.end_with?('!')
+
+      field_name = @name
+      method_name = @method_name
+      fast_method_name = @fast_method_name
+
+      handle_method_conflict(klass, fast_method_name) do
+        klass.define_method fast_method_name do |*args|
+          raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0 or 1)" if args.size > 1
+
+          val = args.first
+
+          # If no value provided, return current stored value
+          return hget(field_name) if val.nil?
+
+          begin
+            # Trace the operation if debugging is enabled
+            Familia.trace :FAST_WRITER, dbclient, "#{field_name}: #{val.inspect}", caller(1..1) if Familia.debug?
+
+            # Convert value for database storage
+            prepared = serialize_value(val)
+            Familia.ld "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+
+            # Use the setter method to update instance variable
+            send(:"#{method_name}=", val) if method_name
+
+            # Persist to database immediately
+            ret = hset(field_name, prepared)
+            ret.zero? || ret.positive?
+          rescue Familia::Problem => e
+            raise "#{fast_method_name} method failed: #{e.message}", e.backtrace
+          end
+        end
+      end
+    end
+
+    # Whether this field should be persisted to the database
+    #
+    # @return [Boolean] true if field should be persisted
+    #
+    def persistent?
+      true
+    end
+
+    def transient?
+      !persistent?
+    end
+
+    # The category for this field type (used for filtering)
+    #
+    # @return [Symbol] the field category
+    #
+    def category
+      :field
+    end
+
+    # Serialize a value for database storage
+    #
+    # Subclasses can override this to customize serialization.
+    # The default implementation passes values through unchanged.
+    #
+    # @param value [Object] The value to serialize
+    # @param record [Object] The record instance (for context)
+    # @return [Object] The serialized value
+    #
+    def serialize(value, _record = nil)
+      value
+    end
+
+    # Deserialize a value from database storage
+    #
+    # Subclasses can override this to customize deserialization.
+    # The default implementation passes values through unchanged.
+    #
+    # @param value [Object] The value to deserialize
+    # @param record [Object] The record instance (for context)
+    # @return [Object] The deserialized value
+    #
+    def deserialize(value, _record = nil)
+      value
+    end
+
+    # Returns all method names generated for this field (used for conflict detection)
+    #
+    # @return [Array<Symbol>] Array of method names this field type generates
+    #
+    def generated_methods
+      [@method_name, @fast_method_name].compact
+    end
+
+    # Enhanced inspection output for debugging
+    #
+    # @return [String] Human-readable representation
+    #
+    def inspect
+      attributes = [
+        "name=#{@name}",
+        "method_name=#{@method_name}",
+        "fast_method_name=#{@fast_method_name}",
+        "on_conflict=#{@on_conflict}",
+        "category=#{category}"
+      ]
+      "#<#{self.class.name} #{attributes.join(' ')}>"
+    end
+    alias to_s inspect
+
+    private
+
+    # Handle method name conflicts during definition
+    #
+    # @param klass [Class] The target class
+    # @param method_name [Symbol] The method name to define
+    # @yield Block that defines the method
+    #
+    def handle_method_conflict(klass, method_name)
+      case @on_conflict
+      when :skip
+        return if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+      when :warn
+        if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+          warn <<~WARNING
+
+            WARNING: Method >>> #{method_name} <<< already exists on #{klass}.
+            Field functionality may be broken. Consider using a different name
+            with field(:#{@name}, as: :other_name)
+
+            Called from:
+            #{Familia.pretty_stack(limit: 3)}
+
+          WARNING
+        end
+      when :raise
+        if klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+          raise ArgumentError, "Method >>> #{method_name} <<< already defined for #{klass}"
+        end
+      when :overwrite
+        # Proceed silently - allow overwrite
+      else
+        raise ArgumentError, "Unknown conflict resolution strategy: #{@on_conflict}"
+      end
+
+      yield
+    end
+  end
+end

data/lib/familia/horreum/connection.rb

@@ -2,7 +2,6 @@
 
 module Familia
   class Horreum
-
     # Familia::Horreum::Connection
     #
     module Connection
@@ -47,36 +46,34 @@ module Familia
       #
       # @note This method works with the global Familia.transaction context when available
       #
-      def transaction
+      def transaction(&)
         # If we're already in a Familia.transaction context, just yield the multi connection
         if Fiber[:familia_transaction]
           yield(Fiber[:familia_transaction])
         else
           # Otherwise, create a local transaction
-          block_result = dbclient.multi do |conn|
-            yield(conn)
-          end
+          block_result = dbclient.multi(&)
         end
         block_result
       end
       alias multi transaction
 
-      def pipeline
+      def pipeline(&)
         # If we're already in a Familia.pipeline context, just yield the pipeline connection
         if Fiber[:familia_pipeline]
           yield(Fiber[:familia_pipeline])
         else
           # Otherwise, create a local transaction
-          block_result = dbclient.pipeline do |conn|
-            yield(conn)
-          end
+          block_result = dbclient.pipeline(&)
         end
         block_result
       end
-
     end
 
-    # Include Connection module for instance methods after it's loaded
+    # include for instance methods after it's loaded. Note that Horreum::Utils
+    # are also included and at one time also has a uri method. This connection
+    # module is also extended for the class level methods. It will require some
+    # disambiguation at some point.
     include Familia::Horreum::Connection
   end
 end

data/lib/familia/horreum/{commands.rb → database_commands.rb}

@@ -1,4 +1,4 @@
-# lib/familia/horreum/commands.rb
+# lib/familia/horreum/database_commands.rb
 
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
@@ -7,7 +7,6 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-
     # Methods that call Database commands (InstanceMethods)
     #
     # NOTE: There is no hgetall for Horreum. This is because Horreum
@@ -16,8 +15,7 @@ module Familia
     # emphasize this, instead of "refreshing" the object with hgetall,
     # just load the object again.
     #
-    module Commands
-
+    module DatabaseCommands
       def move(logical_database)
         dbclient.move dbkey, logical_database
       end
@@ -41,6 +39,7 @@ module Familia
       def exists?(check_size: true)
         key_exists = self.class.dbclient.exists?(dbkey)
         return key_exists unless check_size
+
         key_exists && !size.zero?
       end
 
@@ -83,21 +82,11 @@ module Familia
       end
       alias remove remove_field # deprecated
 
-      def datatype
+      def data_type
         Familia.trace :DATATYPE, dbclient, uri, caller(1..1) if Familia.debug?
         dbclient.type dbkey(suffix)
       end
 
-
-      # Retrieves the prefix for the current instance by delegating to its class.
-      #
-      # @return [String] The prefix associated with the class of the current instance.
-      # @example
-      #   instance.prefix
-      def prefix
-        self.class.prefix
-      end
-
       # For parity with DataType#hgetall
       def hgetall
         Familia.trace :HGETALL, dbclient, uri, caller(1..1) if Familia.debug?
@@ -117,8 +106,8 @@ module Familia
         dbclient.hset dbkey, field, value
       end
 
-      def hmset(hsh={})
-        hsh ||= self.to_h
+      def hmset(hsh = {})
+        hsh ||= to_h
         Familia.trace :HMSET, dbclient, hsh, caller(1..1) if Familia.debug?
         dbclient.hmset dbkey(suffix), hsh
       end
@@ -175,9 +164,8 @@ module Familia
         ret.positive?
       end
       alias clear delete!
-
     end
 
-    include Commands # these become Familia::Horreum instance methods
+    include DatabaseCommands # these become Familia::Horreum instance methods
   end
 end