familia 2.0.0.pre12 → 2.0.0.pre14

data/lib/familia/logging.rb

@@ -17,7 +17,7 @@ module Familia
 
     # Get the severity letter from the thread local variable or use
     # the default. The thread local variable is set in the trace
-    # method in the LoggerTraceRefinement module. The name of the
+    # method in the Familia::Refinements::LoggerTrace module. The name of the
     # variable `severity_letter` is arbitrary and could be anything.
     severity_letter = Thread.current[:severity_letter] || severity_letter
 
@@ -36,7 +36,7 @@ module Familia
   # == Methods:
   # trace::
   #   Logs a message at the TRACE level. This method is only available if the
-  #   LoggerTraceRefinement is used.
+  #   Familia::Refinements::LoggerTrace is used.
   #
   # debug::
   #   Logs a message at the DEBUG level. This is used for low-level system information
@@ -59,14 +59,14 @@ module Familia
   #   that will presumably lead the application to abort.
   #
   # == Usage:
-  # To use the Logging module, you need to include the LoggerTraceRefinement module
+  # To use the Logging module, you need to include the Familia::Refinements::LoggerTrace module
   # and use the `using` keyword to enable the refinement. This will add the TRACE
   # log level and the trace method to the Logger class.
   #
   # Example:
   #   require 'logger'
   #
-  #   module LoggerTraceRefinement
+  #   module Familia::Refinements::LoggerTrace
   #     refine Logger do
   #       TRACE = 0
   #
@@ -76,7 +76,7 @@ module Familia
   #     end
   #   end
   #
-  #   using LoggerTraceRefinement
+  #   using Familia::Refinements::LoggerTrace
   #
   #   logger = Logger.new(STDOUT)
   #   logger.trace("This is a trace message")
@@ -86,13 +86,13 @@ module Familia
   #   logger.error("This is an error message")
   #   logger.fatal("This is a fatal message")
   #
-  # In this example, the LoggerTraceRefinement module is defined with a refinement
+  # In this example, the Familia::Refinements::LoggerTrace module is defined with a refinement
   # for the Logger class. The TRACE constant and trace method are added to the Logger
   # class within the refinement. The `using` keyword is used to apply the refinement
   # in the scope where it's needed.
   #
   # == Conditions:
-  # The trace method and TRACE log level are only available if the LoggerTraceRefinement
+  # The trace method and TRACE log level are only available if the Familia::Refinements::LoggerTrace
   # module is used with the `using` keyword. Without this, the Logger class will not
   # have the trace method or the TRACE log level.
   #
@@ -103,7 +103,9 @@ module Familia
     attr_reader :logger
 
     # Gives our logger the ability to use our trace method.
-    using LoggerTraceRefinement if LoggerTraceRefinement::ENABLED
+    if Familia::Refinements::LoggerTrace::ENABLED
+      using Familia::Refinements::LoggerTrace
+    end
 
     def info(*msg)
       @logger.info(*msg)
@@ -140,13 +142,13 @@ module Familia
     #
     # @return [nil]
     #
-    # @note This method only executes if LoggerTraceRefinement::ENABLED is true.
+    # @note This method only executes if Familia::Refinements::LoggerTrace::ENABLED is true.
     # @note The dbclient can be a Database object, Redis::Future (used in
     #   pipelined and multi blocks), or nil (when the database connection isn't
     #   relevant).
     #
     def trace(label, dbclient, ident, context = nil)
-      return unless LoggerTraceRefinement::ENABLED
+      return unless Familia::Refinements::LoggerTrace::ENABLED
 
       # Usually dbclient is a Database object, but it could be
       # a Redis::Future which is what is used inside of pipelined

data/lib/familia/refinements/logger_trace.rb

@@ -0,0 +1,57 @@
+# lib/familia/refinements/logger_trace.rb
+
+require 'pathname'
+require 'logger'
+
+# Controls whether tracing is enabled via an environment variable
+FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
+
+# Familia::Refinements::LoggerTrace
+#
+# This module adds a 'trace' log level to the Ruby Logger class.
+# It is enabled when the FAMILIA_TRACE environment variable is set to
+# '1', 'true', or 'yes' (case-insensitive).
+#
+# @example Enabling trace logging
+#   # Set environment variable
+#   ENV['FAMILIA_TRACE'] = 'true'
+#
+#   # In your Ruby code
+#   require 'logger'
+#   using Familia::Refinements::LoggerTrace
+#
+#   logger = Logger.new(STDOUT)
+#   logger.trace("This is a trace message")
+#
+module Familia
+  module Refinements
+
+    # Familia::Refinements::LoggerTrace
+    module LoggerTrace
+      unless defined?(ENABLED)
+        # Indicates whether trace logging is enabled
+        ENABLED = %w[1 true yes].include?(FAMILIA_TRACE).freeze
+        # The numeric level for trace logging (same as DEBUG)
+        TRACE = 0
+      end
+
+      refine Logger do
+        ##
+        # Logs a message at the TRACE level.
+        #
+        # @param progname [String] The program name to include in the log message
+        # @yield A block that evaluates to the message to log
+        # @return [true] Always returns true
+        #
+        # @example Logging a trace message
+        #   logger.trace("MyApp") { "Detailed trace information" }
+        def trace(progname = nil, &block)
+          Thread.current[:severity_letter] = 'T'
+          add(Familia::Refinements::LoggerTrace::TRACE, nil, progname, &block)
+        ensure
+          Thread.current[:severity_letter] = nil
+        end
+      end
+    end
+  end
+end

data/lib/familia/refinements/snake_case.rb

@@ -0,0 +1,40 @@
+# lib/familia/refinements/snake_case.rb
+
+module Familia
+  module Refinements
+    module SnakeCase
+      # We refine String rather than Class or Module because this method operates on
+      # string representations of class names (like those from `Class#name`) rather
+      # than the class objects themselves. Refining String is safer because it
+      # limits its scope to only the subset string manipulation contexts where it is
+      # used.
+      #
+      # Appropriate for converting Ruby class names to database table names, config
+      # keys, part of a path or any other snake_case identifiers. The only situation
+      # it is not appropriate for is investigating actual snakes.
+      refine String do
+        # Converts a string from PascalCase/camelCase to snake_case format.
+        #
+        # @return [String] the snake_case version of the string
+        #
+        # @example Converting simple CamelCase
+        #   "FirstName".snake_case #=> "first_name"
+        #
+        # @example Converting PascalCase with acronyms
+        #   XMLHttpRequest.name.snake_case #=> "xml_http_request"
+        #
+        # @example Converting namespaced class names
+        #   "MyApp::UserAccount".snake_case #=> "user_account"
+        #
+        # @example Handling mixed case with numbers
+        #   "parseHTML5Document".snake_case #=> "parse_html5_document"
+        def snake_case
+          split('::').last
+                     .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                     .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                     .downcase
+        end
+      end
+    end
+  end
+end

data/lib/familia/refinements/time_literals.rb

@@ -0,0 +1,279 @@
+# lib/familia/refinements/time_literals.rb
+
+module Familia
+  module Refinements
+
+    # Familia::Refinements::TimeLiterals
+    #
+    # This module provides a set of refinements for `Numeric` and `String` to
+    # enable readable and expressive time duration and timestamp manipulation.
+    #
+    # The name "TimeLiterals" reflects its core purpose: to allow us to treat
+    # numeric values directly as "literals" of time units (e.g., `5.minutes`,
+    # `1.day`). It extends this concept to include conversions between these
+    # literal time quantities, parsing string representations of time
+    # durations, and performing common timestamp-based calculations
+    # in an intuitive manner.
+    #
+    # @example Expressing durations
+    #   5.minutes.ago           #=> A Time object 5 minutes in the past
+    #   1.day.from_now          #=> A Time object 1 day in the future
+    #   (2.5).hours             #=> 9000.0 (seconds)
+    #
+    # @example Converting between units
+    #   3600.in_hours           #=> 1.0
+    #   86400.in_days           #=> 1.0
+    #
+    # @example Parsing string durations
+    #   "30m".in_seconds        #=> 1800.0
+    #   "2.5h".in_seconds       #=> 9000.0
+    #
+    # @example Timestamp calculations
+    #   timestamp = 2.days.ago.to_i
+    #   timestamp.days_old      #=> ~2.0
+    #   timestamp.older_than?(1.day) #=> true
+    #
+    # @note `to_bytes` also lives here until we find it a better home!
+    #
+    module TimeLiterals
+      # Time unit constants
+      PER_MICROSECOND = 0.000001
+      PER_MILLISECOND = 0.001
+      PER_MINUTE      = 60.0
+      PER_HOUR        = 3600.0
+      PER_DAY         = 86_400.0
+      PER_WEEK        = 604_800.0
+      PER_YEAR        = 31_556_952.0 # 365.2425 days (Gregorian year)
+      PER_MONTH       = PER_YEAR / 12.0 # 30.437 days (consistent with Gregorian year)
+
+      UNIT_METHODS = {
+        'y' => :years,
+        'year' => :years,
+        'years' => :years,
+        'mo' => :months,
+        'month' => :months,
+        'months' => :months,
+        'w' => :weeks,
+        'week' => :weeks,
+        'weeks' => :weeks,
+        'd' => :days,
+        'day' => :days,
+        'days' => :days,
+        'h' => :hours,
+        'hour' => :hours,
+        'hours' => :hours,
+        'm' => :minutes,
+        'minute' => :minutes,
+        'minutes' => :minutes,
+        'ms' => :milliseconds,
+        'millisecond' => :milliseconds,
+        'milliseconds' => :milliseconds,
+        'us' => :microseconds,
+        'microsecond' => :microseconds,
+        'microseconds' => :microseconds,
+        'μs' => :microseconds,
+      }.freeze
+
+      refine Numeric do
+        def microseconds = seconds * PER_MICROSECOND
+        def milliseconds = seconds * PER_MILLISECOND
+        def seconds      = self
+        def minutes      = seconds * PER_MINUTE
+        def hours        = seconds * PER_HOUR
+        def days         = seconds * PER_DAY
+        def weeks        = seconds * PER_WEEK
+        def months       = seconds * PER_MONTH
+        def years        = seconds * PER_YEAR
+
+        # Aliases with singular forms
+        alias_method :microsecond, :microseconds
+        alias_method :millisecond, :milliseconds
+        alias_method :second,      :seconds
+        alias_method :minute,      :minutes
+        alias_method :hour,        :hours
+        alias_method :day,         :days
+        alias_method :week,        :weeks
+        alias_method :month,       :months
+        alias_method :year,        :years
+
+        # Shortest aliases
+        alias_method :ms, :milliseconds
+        alias_method :μs, :microseconds
+
+        # Seconds -> other time units
+        def in_years        = seconds / PER_YEAR
+        def in_months       = seconds / PER_MONTH
+        def in_weeks        = seconds / PER_WEEK
+        def in_days         = seconds / PER_DAY
+        def in_hours        = seconds / PER_HOUR
+        def in_minutes      = seconds / PER_MINUTE
+        def in_milliseconds = seconds / PER_MILLISECOND
+        def in_microseconds = seconds / PER_MICROSECOND
+        # For semantic purposes
+        def in_seconds      = seconds
+
+        # Time manipulation
+        def ago         = Time.now.utc - seconds
+        def from_now    = Time.now.utc + seconds
+        def before(time) = time - seconds
+        def after(time)  = time + seconds
+        def in_time = Time.at(seconds).utc
+
+        # Milliseconds conversion
+        def to_ms = seconds * 1000.0
+
+        # Converts seconds to specified time unit
+        #
+        # @param u [String, Symbol] Unit to convert to
+        # @return [Float] Converted time value
+        def in_seconds(u = nil)
+          return self unless u
+
+          case UNIT_METHODS.fetch(u.to_s.downcase, nil)
+          when :milliseconds then self * PER_MILLISECOND
+          when :microseconds then self * PER_MICROSECOND
+          when :minutes then self * PER_MINUTE
+          when :hours then self * PER_HOUR
+          when :days then self * PER_DAY
+          when :weeks then self * PER_WEEK
+          when :months then self * PER_MONTH
+          when :years then self * PER_YEAR
+          else self
+          end
+        end
+
+        # Converts the number to a human-readable string representation
+        #
+        # @return [String] A formatted string e.g. "1 day" or "10 seconds"
+        #
+        # @example
+        #   10.to_humanize #=> "10 seconds"
+        #   60.to_humanize #=> "1 minute"
+        #   3600.to_humanize #=> "1 hour"
+        #   86400.to_humanize #=> "1 day"
+        def humanize
+          gte_zero = positive? || zero?
+          duration = (gte_zero ? self : abs) # let's keep it positive up in here
+          text = case (s = duration.to_i)
+                in 0..59 then "#{s} second#{'s' if s != 1}"
+                in 60..3599 then "#{s /= 60} minute#{'s' if s != 1}"
+                in 3600..86_399 then "#{s /= 3600} hour#{'s' if s != 1}"
+                else "#{s /= 86_400} day#{'s' if s != 1}"
+                end
+          gte_zero ? text : "#{text} ago"
+        end
+
+        # Converts the number to a human-readable byte representation using binary units
+        #
+        # @return [String] A formatted string of bytes, KiB, MiB, GiB, or TiB
+        #
+        # @example
+        #   1024.to_bytes      #=> "1.00 KiB"
+        #   2_097_152.to_bytes #=> "2.00 MiB"
+        #   3_221_225_472.to_bytes #=> "3.00 GiB"
+        #
+        def to_bytes
+          units = %w[B KiB MiB GiB TiB]
+          size  = abs.to_f
+          unit  = 0
+
+          while size >= 1024 && unit < units.length - 1
+            size /= 1024
+            unit += 1
+          end
+
+          format('%3.2f %s', size, units[unit])
+        end
+
+        # Calculates age of timestamp in specified unit from reference time
+        #
+        # @param unit [String, Symbol] Time unit ('days', 'hours', 'minutes', 'weeks')
+        # @param from_time [Time, nil] Reference time (defaults to Time.now.utc)
+        # @return [Float] Age in specified unit
+        # @example
+        #   timestamp = 2.days.ago.to_i
+        #   timestamp.age_in(:days)         #=> ~2.0
+        #   timestamp.age_in('hours')       #=> ~48.0
+        #   timestamp.age_in(:days, 1.day.ago) #=> ~1.0
+        def age_in(unit, from_time = nil)
+          from_time ||= Time.now.utc
+          age_seconds = from_time.to_f - to_f
+          case UNIT_METHODS.fetch(unit.to_s.downcase, nil)
+          when :days then age_seconds / PER_DAY
+          when :hours then age_seconds / PER_HOUR
+          when :minutes then age_seconds / PER_MINUTE
+          when :weeks then age_seconds / PER_WEEK
+          when :months then age_seconds / PER_MONTH
+          when :years then age_seconds / PER_YEAR
+          else age_seconds
+          end
+        end
+
+        # Convenience methods for `age_in(unit)` calls.
+        #
+        # @param from_time [Time, nil] Reference time (defaults to Time.now.utc)
+        # @return [Float] Age in days
+        # @example
+        #   timestamp.days_old    #=> 2.5
+        def days_old(*) = age_in(:days, *)
+        def hours_old(*) = age_in(:hours, *)
+        def minutes_old(*) = age_in(:minutes, *)
+        def weeks_old(*) = age_in(:weeks, *)
+        def months_old(*) = age_in(:months, *)
+        def years_old(*) = age_in(:years, *)
+
+        # Checks if timestamp is older than specified duration in seconds
+        #
+        # @param duration [Numeric] Duration in seconds to compare against
+        # @return [Boolean] true if timestamp is older than duration
+        # @note Both older_than? and newer_than? can return false when timestamp
+        #   is within the same second. Use within? to check this case.
+        #
+        # @example
+        #   Time.now.older_than?(1.second)    #=> false
+        def older_than?(duration)
+          self < (Time.now.utc.to_f - duration)
+        end
+
+        # Checks if timestamp is newer than specified duration in the future
+        #
+        # @example
+        #   Time.now.newer_than?(1.second)    #=> false
+        def newer_than?(duration)
+          self > (Time.now.utc.to_f + duration)
+        end
+
+        # Checks if timestamp is within specified duration of now (past or future)
+        #
+        # @param duration [Numeric] Duration in seconds to compare against
+        # @return [Boolean] true if timestamp is within duration of now
+        # @example
+        #   30.minutes.ago.to_i.within?(1.hour)     #=> true
+        #   30.minutes.from_now.to_i.within?(1.hour) #=> true
+        #   2.hours.ago.to_i.within?(1.hour)        #=> false
+        def within?(duration)
+          (self - Time.now.utc.to_f).abs <= duration
+        end
+      end
+
+      refine ::String do
+        # Converts string time representation to seconds
+        #
+        # @example
+        #   "60m".in_seconds #=> 3600.0
+        #   "2.5h".in_seconds #=> 9000.0
+        #   "1y".in_seconds #=> 31536000.0
+        #
+        # @return [Float, nil] Time in seconds or nil if invalid
+        def in_seconds
+          q, u = scan(/([\d.]+)([a-zA-Zμs]+)?/).flatten
+          return nil unless q
+
+          q   = q.to_f
+          u ||= 's'
+          q.in_seconds(u)
+        end
+      end
+    end
+  end
+end

data/lib/familia/refinements.rb

@@ -1,51 +1,5 @@
 # lib/familia/refinements.rb
 
-require 'pathname'
-require 'logger'
-
-# Controls whether tracing is enabled via an environment variable
-FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
-
-# LoggerTraceRefinement
-#
-# This module adds a 'trace' log level to the Ruby Logger class.
-# It is enabled when the FAMILIA_TRACE environment variable is set to
-# '1', 'true', or 'yes' (case-insensitive).
-#
-# @example Enabling trace logging
-#   # Set environment variable
-#   ENV['FAMILIA_TRACE'] = 'true'
-#
-#   # In your Ruby code
-#   require 'logger'
-#   using LoggerTraceRefinement
-#
-#   logger = Logger.new(STDOUT)
-#   logger.trace("This is a trace message")
-#
-module LoggerTraceRefinement
-  unless defined?(ENABLED)
-    # Indicates whether trace logging is enabled
-    ENABLED = %w[1 true yes].include?(FAMILIA_TRACE).freeze
-    # The numeric level for trace logging (same as DEBUG)
-    TRACE = 0
-  end
-
-  refine Logger do
-    ##
-    # Logs a message at the TRACE level.
-    #
-    # @param progname [String] The program name to include in the log message
-    # @yield A block that evaluates to the message to log
-    # @return [true] Always returns true
-    #
-    # @example Logging a trace message
-    #   logger.trace("MyApp") { "Detailed trace information" }
-    def trace(progname = nil, &block)
-      Thread.current[:severity_letter] = 'T'
-      add(LoggerTraceRefinement::TRACE, nil, progname, &block)
-    ensure
-      Thread.current[:severity_letter] = nil
-    end
-  end
-end
+require_relative 'refinements/logger_trace'
+require_relative 'refinements/snake_case'
+require_relative 'refinements/time_literals'

data/lib/familia/utils.rb

@@ -6,6 +6,8 @@ module Familia
   #
   module Utils
 
+    using Familia::Refinements::TimeLiterals
+
     # Joins array elements with Familia delimiter
     # @param val [Array] elements to join
     # @return [String] joined string

data/lib/familia/validation/{test_helpers.rb → validation_helpers.rb}

@@ -1,4 +1,4 @@
-# lib/familia/validation/test_helpers.rb
+# lib/familia/validation/validation_helpers.rb
 
 module Familia
   module Validation
@@ -7,7 +7,7 @@ module Familia
     # and automatic setup/cleanup for command validation tests.
     #
     # @example Basic usage in a try file
-    #   require_relative '../validation/test_helpers'
+    #   require_relative '../validation/validation_helpers'
     #   extend Familia::Validation::TestHelpers
     #
     #   ## User save should execute expected Redis commands

data/lib/familia/validation.rb

@@ -51,7 +51,7 @@
 require_relative 'validation/command_recorder'
 require_relative 'validation/expectations'
 require_relative 'validation/validator'
-require_relative 'validation/test_helpers'
+require_relative 'validation/validation_helpers'
 
 module Familia
   module Validation

data/lib/familia/version.rb

@@ -2,5 +2,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre12'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre14'.freeze unless defined?(Familia::VERSION)
 end

data/lib/familia.rb

@@ -1,11 +1,12 @@
 # lib/familia.rb
 
-require 'json'
+require 'oj'
 require 'redis'
 require 'uri/valkey'
 require 'connection_pool'
 
-require_relative 'familia/core_ext'
+# OJ configuration is handled internally by Familia::JsonSerializer
+
 require_relative 'familia/refinements'
 require_relative 'familia/errors'
 require_relative 'familia/version'
@@ -71,6 +72,7 @@ module Familia
   require_relative 'familia/connection'
   require_relative 'familia/settings'
   require_relative 'familia/utils'
+  require_relative 'familia/json_serializer'
 
   extend SecureIdentifier
   extend Connection
@@ -80,8 +82,18 @@ module Familia
 end
 
 require_relative 'familia/base'
+require_relative 'familia/features/autoloadable'
 require_relative 'familia/features'
-require_relative 'familia/features/autoloader'
 require_relative 'familia/data_type'
 require_relative 'familia/horreum'
 require_relative 'familia/encryption'
+
+# Ensure JSON constant is available for backward compatibility with existing code
+# This approach is safer than monkey-patching core classes globally
+begin
+  require 'json'
+rescue LoadError
+  # If json gem is not available, define a minimal JSON constant
+  # that delegates to Familia::JsonSerializer for compatibility
+  JSON = Familia::JsonSerializer
+end