familia 2.0.0.pre12 → 2.0.0.pre14

data/examples/autoloader/mega_customer.rb

@@ -0,0 +1,17 @@
+# examples/autoloader/mega_customer.rb
+
+require_relative '../../lib/familia'
+
+class MegaCustomer < Familia::Horreum
+  field :custid
+  field :username
+  field :email
+  field :fname
+  field :lname
+  field :display_name
+  field :created_at
+  field :updated_at
+
+  feature :safe_dump
+  # feature :deprecated_fields
+end

data/examples/safe_dump.rb

@@ -273,7 +273,7 @@ puts "LegacyModel fields after set_safe_dump_fields: #{LegacyModel.safe_dump_fie
 puts
 puts '=== Cleaning up test data ==='
 [User, Product, Order, Address, Customer, LegacyModel].each do |klass|
-  klass.redis.del(klass.redis.keys("#{klass.name.downcase}:*"))
+  klass.dbclient.del(klass.dbclient.keys("#{klass.name.downcase}:*"))
 rescue StandardError => e
   puts "Error cleaning #{klass}: #{e.message}"
 end

data/familia.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'connection_pool', '~> 2.5'
   spec.add_dependency 'csv', '~> 3.3'
   spec.add_dependency 'logger', '~> 1.7'
+  spec.add_dependency 'oj', '~> 3.16'
   spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'

data/lib/familia/autoloader.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Familia
+  # Provides autoloading functionality for Ruby files based on patterns and conventions.
+  #
+  # Used by the Features module at library startup to load feature files, and available
+  # as a utility for other modules requiring file autoloading capabilities.
+  module Autoloader
+    # Autoloads Ruby files matching the given patterns.
+    #
+    # @param patterns [String, Array<String>] file patterns to match (supports Dir.glob patterns)
+    # @param exclude [Array<String>] basenames to exclude from loading
+    # @param log_prefix [String] prefix for debug logging messages
+    def self.autoload_files(patterns, exclude: [], log_prefix: 'Autoloader')
+      patterns = Array(patterns)
+
+      patterns.each do |pattern|
+        Dir.glob(pattern).each do |file_path|
+          basename = File.basename(file_path)
+
+          # Skip excluded files
+          next if exclude.include?(basename)
+
+          Familia.trace :FEATURE, nil, "[#{log_prefix}] Loading #{file_path}", caller(1..1) if Familia.debug?
+          require File.expand_path(file_path)
+        end
+      end
+    end
+
+    # Autoloads feature files when this module is included.
+    #
+    # Discovers and loads all Ruby files in the features/ directory relative to the
+    # including module's location. Typically used by Familia::Features.
+    #
+    # @param base [Module] the module including this autoloader
+    def self.included(base)
+      # Get the directory where the including module is defined
+      # This should be lib/familia for the Features module
+      base_path = File.dirname(caller_locations(1, 1).first.path)
+      features_dir = File.join(base_path, 'features')
+
+      Familia.ld "[DEBUG] Autoloader loading features from #{features_dir}"
+
+      return unless Dir.exist?(features_dir)
+
+      # Use the shared autoload_files method
+      autoload_files(
+        File.join(features_dir, '*.rb'),
+        log_prefix: 'Autoloader'
+      )
+    end
+  end
+end

data/lib/familia/base.rb

@@ -14,6 +14,9 @@ module Familia
   # @see Familia::DataType
   #
   module Base
+
+    using Familia::Refinements::TimeLiterals
+
     @features_available = nil
     @feature_definitions = nil
     @dump_method = :to_json
@@ -24,6 +27,8 @@ module Familia
       base.extend(ClassMethods)
     end
 
+    # Familia::Base::ClassMethods
+    #
     module ClassMethods
       attr_reader :features_available, :feature_definitions
       attr_accessor :dump_method, :load_method

data/lib/familia/data_type.rb

@@ -3,6 +3,8 @@
 require_relative 'data_type/commands'
 require_relative 'data_type/serialization'
 
+# Familia
+#
 module Familia
   # DataType - Base class for Database data type wrappers
   #
@@ -14,6 +16,8 @@ module Familia
     include Familia::Base
     extend Familia::Features
 
+    using Familia::Refinements::TimeLiterals
+
     @registered_types = {}
     @valid_options = %i[class parent default_expiration default logical_database dbkey dbclient suffix prefix]
     @logical_database = nil

data/lib/familia/encryption/encrypted_data.rb

@@ -9,7 +9,7 @@ module Familia
         return false unless json_string.kind_of?(::String)
 
         begin
-          parsed = JSON.parse(json_string, symbolize_names: true)
+          parsed = Familia::JsonSerializer.parse(json_string, symbolize_names: true)
           return false unless parsed.is_a?(Hash)
 
           # Check for required fields
@@ -17,7 +17,7 @@ module Familia
           result = required_fields.all? { |field| parsed.key?(field) }
           Familia.ld "[valid?] result: #{result}, parsed: #{parsed}, required: #{required_fields}"
           result
-        rescue JSON::ParserError => e
+        rescue Familia::SerializerError => e
           Familia.ld "[valid?] JSON error: #{e.message}"
           false
         end
@@ -31,8 +31,8 @@ module Familia
         end
 
         begin
-          parsed = JSON.parse(json_string, symbolize_names: true)
-        rescue JSON::ParserError => e
+          parsed = Familia::JsonSerializer.parse(json_string, symbolize_names: true)
+        rescue Familia::SerializerError => e
           raise EncryptionError, "Invalid JSON structure: #{e.message}"
         end
 

data/lib/familia/encryption/manager.rb

@@ -19,13 +19,15 @@ module Familia
 
         result = @provider.encrypt(plaintext, key, additional_data)
 
-        Familia::Encryption::EncryptedData.new(
+        encrypted_data = Familia::Encryption::EncryptedData.new(
           algorithm: @provider.algorithm,
           nonce: Base64.strict_encode64(result[:nonce]),
           ciphertext: Base64.strict_encode64(result[:ciphertext]),
           auth_tag: Base64.strict_encode64(result[:auth_tag]),
           key_version: current_key_version
-        ).to_h.to_json
+        ).to_h
+
+        Familia::JsonSerializer.dump(encrypted_data)
       ensure
         Familia::Encryption.secure_wipe(key) if key
       end
@@ -37,7 +39,7 @@ module Familia
         Familia::Encryption.derivation_count.increment
 
         begin
-          data = Familia::Encryption::EncryptedData.new(**JSON.parse(encrypted_json, symbolize_names: true))
+          data = Familia::Encryption::EncryptedData.new(**Familia::JsonSerializer.parse(encrypted_json, symbolize_names: true))
 
           # Validate algorithm support
           provider = Registry.get(data.algorithm)
@@ -51,7 +53,7 @@ module Familia
           provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
         rescue EncryptionError
           raise
-        rescue JSON::ParserError => e
+        rescue Familia::SerializerError => e
           raise EncryptionError, "Invalid JSON structure: #{e.message}"
         rescue StandardError => e
           raise EncryptionError, "Decryption failed: #{e.message}"

data/lib/familia/encryption.rb

@@ -1,7 +1,7 @@
 # lib/familia/encryption.rb
 
 require 'base64'
-require 'json'
+require 'oj'
 require 'openssl'
 
 # Provider system components

data/lib/familia/errors.rb

@@ -6,6 +6,9 @@ module Familia
   class NonUniqueKey < Problem; end
 
   class FieldTypeError < Problem; end
+  class AutoloadError < Problem; end
+
+  class SerializerError < Problem; end
 
   class HighRiskFactor < Problem
     attr_reader :value

data/lib/familia/features/autoloadable.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative '../refinements/snake_case'
+
+module Familia
+  module Features
+    # Enables automatic loading of feature-specific files when a feature is included in a user class.
+    #
+    # When included in a feature module, adds ClassMethods that detect when the feature is
+    # included in user classes, derives the feature name, and autoloads files matching
+    # conventional patterns in the user class's directory structure.
+    module Autoloadable
+      using Familia::Refinements::SnakeCase
+
+      # Sets up a feature module with autoloading capabilities.
+      #
+      # Extends the feature module with ClassMethods to handle post-inclusion autoloading.
+      #
+      # @param feature_module [Module] the feature module being enhanced
+      def self.included(feature_module)
+        feature_module.extend(ClassMethods)
+      end
+
+      # Methods added to feature modules that include Autoloadable.
+      module ClassMethods
+        # Triggered when the feature is included in a user class.
+        #
+        # Sets up for post-inclusion autoloading. The actual autoloading
+        # is deferred until after feature setup completes.
+        #
+        # @param base [Class] the user class including this feature
+        def included(base)
+          # Call parent included method if it exists (defensive programming for mixed-in contexts)
+          super if defined?(super)
+
+          # No autoloading here - it's deferred to post_inclusion_autoload
+          # to ensure the feature is fully set up before extension files are loaded
+        end
+
+        # Called by the feature system after the feature is fully included.
+        #
+        # Uses const_source_location to determine where the base class is defined,
+        # then autoloads feature-specific extension files from that location.
+        #
+        # @param base [Class] the class that included this feature
+        # @param feature_name [Symbol] the name of the feature
+        # @param options [Hash] feature options (unused but kept for compatibility)
+        def post_inclusion_autoload(base, feature_name, options)
+          Familia.trace :FEATURE, nil, "[Autoloadable] post_inclusion_autoload called for #{feature_name} on #{base.name || base}", caller(1..1) if Familia.debug?
+
+          # Get the source location via Ruby's built-in introspection
+          source_location = nil
+
+          # Check for named classes that can be looked up via const_source_location
+          # Class#name always returns String or nil, so type check is redundant
+          if base.name && !base.name.empty?
+            begin
+              location_info = Module.const_source_location(base.name)
+              source_location = location_info&.first
+              Familia.trace :FEATURE, nil, "[Autoloadable] Source location for #{base.name}: #{source_location}", caller(1..1) if Familia.debug?
+            rescue NameError => e
+              # Handle cases where the class name is not a valid constant name
+              # This can happen in test environments with dynamically created classes
+              Familia.trace :FEATURE, nil, "[Autoloadable] Cannot resolve source location for #{base.name}: #{e.message}", caller(1..1) if Familia.debug?
+            end
+          else
+            Familia.trace :FEATURE, nil, "[Autoloadable] Skipping source location detection - base.name=#{base.name.inspect}", caller(1..1) if Familia.debug?
+          end
+
+          # Autoload feature-specific files if we have a valid source location
+          if source_location && !source_location.include?('-e') # Skip eval/irb contexts
+            Familia.trace :FEATURE, nil, "[Autoloadable] Calling autoload_feature_files with #{source_location}", caller(1..1) if Familia.debug?
+            autoload_feature_files(source_location, base, feature_name.to_s.snake_case)
+          else
+            Familia.trace :FEATURE, nil, "[Autoloadable] Skipping autoload - no valid source location", caller(1..1) if Familia.debug?
+          end
+        end
+
+        private
+
+        # Autoloads feature-specific files from conventional directory patterns.
+        #
+        # Searches for files matching patterns like:
+        # - model_name/feature_name_*.rb
+        # - model_name/features/feature_name_*.rb
+        # - features/feature_name_*.rb
+        #
+        # @param location_path [String] path where the user class is defined
+        # @param base [Class] the user class including the feature
+        # @param feature_name [String] snake_case name of the feature
+        def autoload_feature_files(location_path, base, feature_name)
+          base_dir = File.dirname(location_path)
+
+          # Handle anonymous classes gracefully
+          model_name = base.name ? base.name.snake_case : "anonymous_#{base.object_id}"
+
+          # Look for feature-specific files in conventional locations
+          patterns = [
+            File.join(base_dir, model_name, "#{feature_name}_*.rb"),
+            File.join(base_dir, model_name, 'features', "#{feature_name}_*.rb"),
+            File.join(base_dir, 'features', "#{feature_name}_*.rb"),
+          ]
+
+          # Use Autoloader's shared method for consistent file loading
+          Familia::Autoloader.autoload_files(
+            patterns,
+            log_prefix: "Autoloadable(#{feature_name})"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -37,6 +37,8 @@
 #   user.to_json                            # Safe - contains [CONCEALED]
 #
 class ConcealedString
+  REDACTED = '[CONCEALED]'.freeze
+
   # Create a concealed string wrapper
   #
   # @param encrypted_data [String] The encrypted JSON data
@@ -264,9 +266,9 @@ class ConcealedString
     { concealed: true }
   end
 
-  # Prevent exposure in JSON serialization
+  # Prevent exposure in JSON serialization - fail closed for security
   def to_json(*)
-    '"[CONCEALED]"'
+    raise Familia::SerializerError, "ConcealedString cannot be serialized to JSON"
   end
 
   # Prevent exposure in Rails serialization (as_json -> to_json)

data/lib/familia/features/expiration.rb

@@ -149,6 +149,8 @@ module Familia
     module Expiration
       @default_expiration = nil
 
+      using Familia::Refinements::TimeLiterals
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
@@ -160,6 +162,8 @@ module Familia
         base.instance_variable_set(:@default_expiration, @default_expiration)
       end
 
+      # Familia::Expiration::ClassMethods
+      #
       module ClassMethods
         # Set the default expiration time for instances of this class
         #

data/lib/familia/features/external_identifier.rb

@@ -99,7 +99,7 @@ module Familia
             klass.define_method :"#{method_name}=" do |value|
               # Remove old mapping if extid is changing
               old_value = instance_variable_get(:"@#{field_name}")
-              self.class.extid_lookup.del(old_value) if old_value && old_value != value && respond_to?(:identifier)
+              self.class.extid_lookup.remove_field(old_value) if old_value && old_value != value
 
               # Set the new value
               instance_variable_set(:"@#{field_name}", value)
@@ -153,7 +153,7 @@ module Familia
           find_by_id(primary_id)
         rescue Familia::NotFound
           # If the object was deleted but mapping wasn't cleaned up
-          extid_lookup.del(extid)
+          extid_lookup.remove_field(extid)
           nil
         end
       end
@@ -236,7 +236,7 @@ module Familia
       def destroy!
         # Clean up extid mapping when object is destroyed
         current_extid = instance_variable_get(:@extid)
-        self.class.extid_lookup.del(current_extid) if current_extid
+        self.class.extid_lookup.remove_field(current_extid) if current_extid
 
         super if defined?(super)
       end

data/lib/familia/features/quantization.rb

@@ -245,11 +245,16 @@ module Familia
     #   NoDefault.qstamp()  # Uses 10.minutes as fallback quantum
     #
     module Quantization
+
+      using Familia::Refinements::TimeLiterals
+
       def self.included(base)
         Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
         base.extend ClassMethods
       end
 
+      # Familia::Quantization::ClassMethods
+      #
       module ClassMethods
         # Generates a quantized timestamp based on the given parameters
         #

data/lib/familia/features/safe_dump.rb

@@ -1,5 +1,6 @@
 # lib/familia/features/safe_dump.rb
 
+
 # rubocop:disable ThreadSafety/ClassInstanceVariable
 #
 #   Class instance variables are used here for feature configuration
@@ -40,10 +41,16 @@ module Familia::Features
   # of symbols in the order they were defined.
   #
   module SafeDump
+    include Familia::Features::Autoloadable
+    using Familia::Refinements::SnakeCase
+
     @dump_method = :to_json
     @load_method = :from_json
 
     def self.included(base)
+      # Call the Autoloadable module's included method for post-inclusion setup
+      super
+
       Familia.trace(:LOADED, self, base, caller(1..1)) if Familia.debug?
       base.extend ClassMethods
 

data/lib/familia/features.rb

@@ -1,5 +1,8 @@
 # lib/familia/features.rb
 
+# Load the Autoloader first, then use it to load all other features
+require_relative 'autoloader'
+
 module Familia
   FeatureDefinition = Data.define(:name, :depends_on)
 
@@ -22,9 +25,9 @@ module Familia
   # feature options. When you enable a feature with options in different models,
   # each model stores its own separate configuration without interference.
   #
-  # ## Project Organization with Autoloader
+  # ## Project Organization with Autoloadable
   #
-  # For large projects, use {Familia::Features::Autoloader} to automatically load
+  # For large projects, use {Familia::Features::Autoloadable} to automatically load
   # project-specific features from a dedicated directory structure. This helps
   # organize complex models by separating features into individual files.
   #
@@ -54,14 +57,16 @@ module Familia
   #   # In your model file: app/models/customer.rb
   #   class Customer < Familia::Horreum
   #     module Features
-  #       include Familia::Features::Autoloader
+  #       include Familia::Features::Autoloadable
   #       # Automatically loads all .rb files from app/models/customer/features/
   #     end
   #   end
   #
-  # @see Familia::Features::Autoloader For automatic feature loading
+  # @see Familia::Features::Autoloadable For automatic feature loading
   #
   module Features
+    include Familia::Autoloader
+
     @features_enabled = nil
     attr_reader :features_enabled
 
@@ -131,14 +136,23 @@ module Familia
       # Add it to the list available features_enabled for Familia::Base classes.
       features_enabled << feature_name
 
-      # Store feature options if any were provided using the new pattern
-      if options.any?
+      # Always capture and store the calling location for every feature
+      calling_location = caller_locations(1, 1)&.first
+      options[:calling_location] = calling_location&.path
+
+      # Add feature options if the class supports them (Horreum classes)
+      if respond_to?(:add_feature_options)
         add_feature_options(feature_name, **options)
       end
 
       # Extend the Familia::Base subclass (e.g. Customer) with the feature module
       include feature_class
 
+      # Trigger post-inclusion autoloading for features that support it
+      if feature_class.respond_to?(:post_inclusion_autoload)
+        feature_class.post_inclusion_autoload(self, feature_name, options)
+      end
+
       # NOTE: Do we want to extend Familia::DataType here? That would make it
       # possible to call safe_dump on relations fields (e.g. list, zset, hashkey).
       #
@@ -152,13 +166,3 @@ module Familia
     end
   end
 end
-
-# Load all feature files from the features directory
-features_dir = File.join(__dir__, 'features')
-Familia.ld "[DEBUG] Loading features from #{features_dir}"
-if Dir.exist?(features_dir)
-  Dir.glob(File.join(features_dir, '*.rb')).each do |feature_file|
-    Familia.ld "[DEBUG] Loading feature #{feature_file}"
-    require_relative feature_file
-  end
-end

data/lib/familia/field_type.rb

@@ -29,6 +29,8 @@ module Familia
   class FieldType
     attr_reader :name, :options, :method_name, :fast_method_name, :on_conflict, :loggable
 
+    using Familia::Refinements::TimeLiterals
+
     # Initialize a new field type
     #
     # @param name [Symbol] The field name

data/lib/familia/horreum/core/serialization.rb

@@ -470,7 +470,7 @@ module Familia
         # If the distinguisher returns nil, try using the dump_method but only
         # use JSON serialization for complex types that need it.
         if prepared.nil? && (val.is_a?(Hash) || val.is_a?(Array))
-          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : JSON.dump(val)
+          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : Familia::JsonSerializer.dump(val)
         end
 
         # If both the distinguisher and dump_method return nil, log an error
@@ -493,11 +493,11 @@ module Familia
 
         # Try to parse as JSON first for complex types
         begin
-          parsed = JSON.parse(val, symbolize_names: symbolize)
+          parsed = Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
           # Only return parsed value if it's a complex type (Hash/Array)
           # Simple values should remain as strings
           return parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
-        rescue JSON::ParserError
+        rescue Familia::SerializerError
           # Not valid JSON, return as-is
         end
 

data/lib/familia/horreum/subclass/definition.rb

@@ -46,6 +46,8 @@ module Familia
       include Familia::Settings
       include Familia::Horreum::RelatedFieldsManagement # Provides DataType field methods
 
+      using Familia::Refinements::SnakeCase
+
       # Sets or retrieves the unique identifier field for the class.
       #
       # This method defines or returns the field or method that contains the unique
@@ -183,10 +185,7 @@ module Familia
       #
       # @return [String] The underscored class name as a string
       def config_name
-        name.split('::').last
-            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-            .downcase
+        name.snake_case
       end
 
       def dump_method

data/lib/familia/horreum.rb

@@ -31,6 +31,8 @@ module Familia
     include Familia::Horreum::Core
     include Familia::Horreum::Settings
 
+    using Familia::Refinements::TimeLiterals
+
     # Singleton Class Context
     #
     # The code within this block operates on the singleton class (also known as

data/lib/familia/json_serializer.rb

@@ -0,0 +1,70 @@
+# lib/familia/json_serializer.rb
+
+module Familia
+  # JsonSerializer provides a high-performance JSON interface using OJ
+  #
+  # This module wraps OJ with a clean API that can be easily swapped out
+  # or benchmarked against other JSON implementations. Uses OJ's :strict
+  # mode for RFC 7159 compliant JSON output.
+  #
+  # @example Basic usage
+  #   data = { name: 'test', value: 123 }
+  #   json = Familia::JsonSerializer.dump(data)
+  #   parsed = Familia::JsonSerializer.parse(json, symbolize_names: true)
+  #
+  module JsonSerializer
+
+    class << self
+      # Parse JSON string into Ruby objects
+      #
+      # @param source [String] JSON string to parse
+      # @param opts [Hash] parsing options
+      # @option opts [Boolean] :symbolize_names convert hash keys to symbols
+      # @return [Object] parsed Ruby object
+      # @raise [SerializerError] if JSON is malformed
+      def parse(source, opts = {})
+        return nil if source.nil? || source == ''
+
+        symbolize_names = opts[:symbolize_names] || opts['symbolize_names']
+
+        if symbolize_names
+          Oj.load(source, mode: :strict, symbol_keys: true)
+        else
+          Oj.load(source, mode: :strict)
+        end
+      rescue Oj::ParseError, Oj::Error, EncodingError => e
+        raise SerializerError, e.message
+      end
+
+      # Serialize Ruby object to JSON string
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] JSON string
+      def dump(obj)
+        Oj.dump(obj, mode: :strict)
+      rescue Oj::Error, TypeError, EncodingError => e
+        raise SerializerError, e.message
+      end
+
+      # Alias for dump for JSON gem compatibility
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] JSON string
+      def generate(obj)
+        Oj.dump(obj, mode: :strict)
+      rescue Oj::Error, TypeError, EncodingError => e
+        raise SerializerError, e.message
+      end
+
+      # Serialize Ruby object to pretty-formatted JSON string
+      #
+      # @param obj [Object] Ruby object to serialize
+      # @return [String] pretty-formatted JSON string
+      def pretty_generate(obj)
+        Oj.dump(obj, mode: :strict, indent: 2)
+      rescue Oj::Error, TypeError, EncodingError => e
+        raise SerializerError, e.message
+      end
+    end
+  end
+end