familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/json_serializer.rb

@@ -13,7 +13,6 @@ module Familia
   #   parsed = Familia::JsonSerializer.parse(json, symbolize_names: true)
   #
   module JsonSerializer
-
     class << self
       # Parse JSON string into Ruby objects
       #

data/lib/familia/logging.rb

@@ -10,6 +10,7 @@ module Familia
     severity_letter = severity[0] # Get the first letter of the severity
     pid = Process.pid
     thread_id = Thread.current.object_id
+    fiber_id = Fiber.current.object_id
     full_path, line = caller(5..5).first.split(':')[0..1]
     parent_path = Pathname.new(full_path).ascend.find { |p| p.basename.to_s == 'familia' }
     relative_path = full_path.sub(parent_path.to_s, 'familia')
@@ -19,9 +20,9 @@ module Familia
     # the default. The thread local variable is set in the trace
     # 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
+    severity_letter = Fiber[:severity_letter] || severity_letter
 
-    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}: #{msg}  [#{relative_path}:#{line}]\n"
+    "#{severity_letter}, #{utc_datetime} #{pid} #{thread_id}/#{fiber_id}: #{msg}  [#{relative_path}:#{line}]\n"
   end
 
   # The Logging module provides a set of methods and constants for logging messages
@@ -103,9 +104,7 @@ module Familia
     attr_reader :logger
 
     # Gives our logger the ability to use our trace method.
-    if Familia::Refinements::LoggerTrace::ENABLED
-      using Familia::Refinements::LoggerTrace
-    end
+    using Familia::Refinements::LoggerTrace if Familia::Refinements::LoggerTrace::ENABLED
 
     def info(*msg)
       @logger.info(*msg)
@@ -129,16 +128,12 @@ module Familia
     #
     # @param label [Symbol] A label for the trace message (e.g., :EXPAND,
     #   :FROMREDIS, :LOAD, :EXISTS).
-    # @param dbclient [Redis, Redis::Future, nil] The Database instance or
-    #   Future being used.
+    # @param instance_id
     # @param ident [String] An identifier or key related to the operation being
     #   traced.
-    # @param context [Array<String>, String, nil] The calling context, typically
-    #   obtained from `caller` or `caller.first`. Default is nil.
+    # @param extra_context [Array<String>, String, nil] Any extra details to include.
     #
-    # @example
-    #   Familia.trace :LOAD, Familia.dbclient(uri), objkey, caller(1..1) if
-    #   Familia.debug?
+    # @example Familia.trace :LOAD, Familia.dbclient(uri), objkey if Familia.debug?
     #
     # @return [nil]
     #
@@ -147,110 +142,12 @@ module Familia
     #   pipelined and multi blocks), or nil (when the database connection isn't
     #   relevant).
     #
-    def trace(label, dbclient, ident, context = nil)
+    def trace(label, instance_id = nil, ident = nil, extra_context = nil)
       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
-      # and multi blocks. In some contexts it's nil where the
-      # database connection isn't relevant.
-      instance_id = if dbclient
-                      case dbclient
-                      when Redis
-                        dbclient.id.respond_to?(:to_s) ? dbclient.id.to_s : dbclient.class.name
-                      when Redis::Future
-                        'Redis::Future'
-                      else
-                        dbclient.class.name
-                      end
-                    end
-
-      codeline = if context
-                   context = [context].flatten
-                   context.reject! { |line| line =~ %r{lib/familia} }
-                   context.first
-                 end
-
-      @logger.trace format('[%s] %s -> %s <- at %s', label, instance_id, ident, codeline)
+      # Let the other values show nothing when nil, but make it known for the focused value
+      ident_str = (ident.nil? ? '<nil>' : ident).to_s
+      @logger.trace format('[%s] %s -> %s <-%s', label, instance_id, ident_str, extra_context)
     end
   end
 end
-
-
-__END__
-
-
-### Example 1: Basic Logging
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 2: Setting Log Level
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.level = Logger::WARN
-
-logger.debug("This is a debug message") # Will not be logged
-logger.info("This is an info message")  # Will not be logged
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 3: Customizing Log Format
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.formatter = proc do |severity, datetime, progname, msg|
-  "#{datetime}: #{severity} - #{msg}\n"
-end
-
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 4: Logging with a Program Name
-```ruby
-require 'logger'
-
-logger = Logger.new($stdout)
-logger.progname = 'Familia'
-
-logger.info("This is an info message")
-logger.warn("This is a warning message")
-logger.error("This is an error message")
-```
-
-### Example 5: Logging with a Block
-```ruby
-require 'logger'
-
-# Calling any of the methods above with a block
-#   (affects only the one entry).
-#   Doing so can have two benefits:
-#
-#   - Context: the block can evaluate the entire program context
-#     and create a context-dependent message.
-#   - Performance: the block is not evaluated unless the log level
-#     permits the entry actually to be written:
-#
-#       logger.error { my_slow_message_generator }
-#
-#     Contrast this with the string form, where the string is
-#     always evaluated, regardless of the log level:
-#
-#       logger.error("#{my_slow_message_generator}")
-logger = Logger.new($stdout)
-
-logger.info { "This is an info message" }
-logger.warn { "This is a warning message" }
-logger.error { "This is an error message" }
-```

data/lib/familia/refinements/dear_json.rb

@@ -0,0 +1,122 @@
+# lib/familia/refinements/dear_json.rb
+
+require 'familia/json_serializer'
+
+module Familia
+  module Refinements
+    # DearJson provides standard JSON methods for core Ruby classes using
+    # Familia's secure JsonSerializer (OJ in strict mode).
+    #
+    # This refinement allows developers to use the standard Ruby JSON interface
+    # (as_json, to_json) on Hash and Array objects while ensuring all JSON
+    # serialization goes through Familia's controlled, secure serialization.
+    #
+    # @example Basic usage with refinement
+    #   using Familia::Refinements::DearJson
+    #
+    #   data = { user: user.as_json, tags: user.tags.as_json }
+    #   json = data.to_json  # Uses Familia::JsonSerializer.dump
+    #
+    #   mixed_array = [user, user.tags, { meta: 'info' }]
+    #   json = mixed_array.to_json  # Handles mixed Familia/core objects
+    #
+    # @example Without refinement (manual approach)
+    #   data = { user: user.as_json, tags: user.tags.as_json }
+    #   json = Familia::JsonSerializer.dump(data)
+    #
+    # Security Benefits:
+    # - All JSON serialization uses OJ strict mode
+    # - Prevents accidental exposure of sensitive objects
+    # - Maintains Familia's security-first approach
+    # - Provides familiar Ruby JSON interface
+    #
+    module DearJsonHashMethods
+      # Convert hash to JSON string using Familia's secure JsonSerializer.
+      # This method preprocesses the hash to handle Familia objects properly
+      # by calling as_json on any objects that support it.
+      #
+      # @param options [Hash] Optional parameters (currently unused, for compatibility)
+      # @return [String] JSON string representation
+      #
+      def to_json(options = nil)
+        # Preprocess the hash to handle Familia objects
+        processed_hash = transform_values do |value|
+          if value.respond_to?(:as_json)
+            value.as_json(options)
+          else
+            value
+          end
+        end
+
+        Familia::JsonSerializer.dump(processed_hash)
+      end
+
+      # Convert hash to JSON-serializable representation.
+      # This method recursively calls as_json on nested values to ensure
+      # Familia objects are properly serialized in nested structures.
+      #
+      # @param options [Hash] Optional parameters (currently unused)
+      # @return [Hash] A new hash with all values converted via as_json
+      #
+      def as_json(options = nil)
+        # Create a new hash, calling as_json on each value.
+        transform_values do |value|
+          if value.respond_to?(:as_json)
+            value.as_json(options)
+          else
+            value
+          end
+        end
+      end
+    end
+
+    module DearJsonArrayMethods
+      # Convert array to JSON string using Familia's secure JsonSerializer.
+      # This method preprocesses the array to handle Familia objects properly
+      # by calling as_json on any objects that support it.
+      #
+      # @param options [Hash] Optional parameters (currently unused, for compatibility)
+      # @return [String] JSON string representation
+      #
+      def to_json(options = nil)
+        # Preprocess the array to handle Familia objects
+        processed_array = map do |item|
+          if item.respond_to?(:as_json)
+            item.as_json(options)
+          else
+            item
+          end
+        end
+
+        Familia::JsonSerializer.dump(processed_array)
+      end
+
+      # Convert array to JSON-serializable representation.
+      # This method recursively calls as_json on nested elements to ensure
+      # Familia objects are properly serialized in nested structures.
+      #
+      # @param options [Hash] Optional parameters (currently unused)
+      # @return [Array] A new array with all elements converted via as_json
+      #
+      def as_json(options = nil)
+        # Create a new array, calling as_json on each element.
+        map do |item|
+          if item.respond_to?(:as_json)
+            item.as_json(options)
+          else
+            item
+          end
+        end
+      end
+    end
+    module DearJson
+      refine Hash do
+        import_methods DearJsonHashMethods
+      end
+
+      refine Array do
+        import_methods DearJsonArrayMethods
+      end
+    end
+  end
+end

data/lib/familia/refinements/logger_trace.rb

@@ -13,7 +13,7 @@ FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
 # '1', 'true', or 'yes' (case-insensitive).
 #
 # @example Enabling trace logging
-#   # Set environment variable
+#   # UnsortedSet environment variable
 #   ENV['FAMILIA_TRACE'] = 'true'
 #
 #   # In your Ruby code
@@ -25,8 +25,25 @@ FAMILIA_TRACE = ENV.fetch('FAMILIA_TRACE', 'false').downcase
 #
 module Familia
   module Refinements
-
     # Familia::Refinements::LoggerTrace
+    module LoggerTraceMethods
+      ##
+      # 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, &)
+        Fiber[:severity_letter] = 'T'
+        add(Familia::Refinements::LoggerTrace::TRACE, nil, progname, &)
+      ensure
+        Fiber[:severity_letter] = nil
+      end
+    end
+
     module LoggerTrace
       unless defined?(ENABLED)
         # Indicates whether trace logging is enabled
@@ -36,21 +53,7 @@ module Familia
       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
+        import_methods LoggerTraceMethods
       end
     end
   end

data/lib/familia/refinements/stylize_words.rb

@@ -0,0 +1,65 @@
+# lib/familia/refinements/stylize_words.rb
+
+module Familia
+  module Refinements
+    # Core string transformation methods that can be tested directly
+    module StylizeWordsMethods
+      # 'Models::Participants' -> 'Participants'
+      def demodularize
+        split('::').last
+      end
+
+      # Convert to snake_case from PascalCase/camelCase
+      def snake_case
+        gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2')
+          .gsub(/([a-z\\d])([A-Z])/, '\\1_\\2')
+          .downcase
+      end
+
+      # Convert from plural to singular form using basic English rules
+      def singularize
+        word = to_s
+        if word.end_with?('ies')
+          "#{word[0..-4]}y"
+        elsif word.end_with?('es') && word.length > 3
+          word[0..-3]
+        elsif word.end_with?('s') && word.length > 1
+          word[0..-2]
+        else
+          word
+        end
+      end
+
+      # Convert to camelCase
+      def camelize
+        _ize(:lower)
+      end
+
+      # Convert to PascalCase
+      def pascalize
+        _ize(:upper)
+      end
+
+      private
+
+      def _ize(first_letter)
+        case first_letter
+        when :lower
+          parts = split(/[_-]/)
+          parts.first.downcase + parts[1..].map(&:capitalize).join
+        when :upper
+          split(/[_-]/).map(&:capitalize).join
+        else
+          raise ArgumentError, "Unknown stylization in first_letter: #{first_letter}"
+        end
+      end
+    end
+
+    # Refinement that delegates to the testable methods
+    module StylizeWords
+      refine String do
+        import_methods StylizeWordsMethods
+      end
+    end
+  end
+end

data/lib/familia/refinements/time_literals.rb

@@ -2,7 +2,6 @@
 
 module Familia
   module Refinements
-
     # Familia::Refinements::TimeLiterals
     #
     # This module provides a set of refinements for `Numeric` and `String` to
@@ -74,7 +73,22 @@ module Familia
         'μs' => :microseconds,
       }.freeze
 
-      refine Numeric do
+      # Shared conversion logic
+      def self.convert_to_seconds(value, unit)
+        case UNIT_METHODS.fetch(unit.to_s.downcase, nil)
+        when :milliseconds then value * PER_MILLISECOND
+        when :microseconds then value * PER_MICROSECOND
+        when :minutes then value * PER_MINUTE
+        when :hours then value * PER_HOUR
+        when :days then value * PER_DAY
+        when :weeks then value * PER_WEEK
+        when :months then value * PER_MONTH
+        when :years then value * PER_YEAR
+        else value
+        end
+      end
+
+      module NumericMethods
         def microseconds = seconds * PER_MICROSECOND
         def milliseconds = seconds * PER_MILLISECOND
         def seconds      = self
@@ -86,19 +100,19 @@ module Familia
         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
+        def microsecond = microseconds
+        def millisecond = milliseconds
+        def second = seconds
+        def minute = minutes
+        def hour = hours
+        def day = days
+        def week = weeks
+        def month = months
+        def year = years
 
         # Shortest aliases
-        alias_method :ms, :milliseconds
-        alias_method :μs, :microseconds
+        def ms = milliseconds
+        def μs = microseconds
 
         # Seconds -> other time units
         def in_years        = seconds / PER_YEAR
@@ -109,12 +123,11 @@ module Familia
         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
+        def in_seconds      = seconds # for semantic purposes
 
         # Time manipulation
-        def ago         = Time.now.utc - seconds
-        def from_now    = Time.now.utc + seconds
+        def ago          = Familia.now - seconds
+        def from_now     = Familia.now + seconds
         def before(time) = time - seconds
         def after(time)  = time + seconds
         def in_time = Time.at(seconds).utc
@@ -124,22 +137,10 @@ module Familia
 
         # Converts seconds to specified time unit
         #
-        # @param u [String, Symbol] Unit to convert to
+        # @param unit [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
+        def in_seconds(unit = nil)
+          unit ? TimeLiterals.convert_to_seconds(self, unit) : self
         end
 
         # Converts the number to a human-readable string representation
@@ -154,12 +155,12 @@ module Familia
         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
+          text = case (num = duration.to_i)
+                 in 0..59 then "#{num} second#{'s' if num != 1}"
+                 in 60..3599 then "#{num /= 60} minute#{'s' if num != 1}"
+                 in 3600..86_399 then "#{num /= 3600} hour#{'s' if num != 1}"
+                 else "#{num /= 86_400} day#{'s' if num != 1}"
+                 end
           gte_zero ? text : "#{text} ago"
         end
 
@@ -188,7 +189,7 @@ module Familia
         # 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)
+        # @param from_time [Time, nil] Reference time (defaults to Familia.now)
         # @return [Float] Age in specified unit
         # @example
         #   timestamp = 2.days.ago.to_i
@@ -196,7 +197,7 @@ module Familia
         #   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
+          from_time ||= Familia.now
           age_seconds = from_time.to_f - to_f
           case UNIT_METHODS.fetch(unit.to_s.downcase, nil)
           when :days then age_seconds / PER_DAY
@@ -211,7 +212,7 @@ module Familia
 
         # Convenience methods for `age_in(unit)` calls.
         #
-        # @param from_time [Time, nil] Reference time (defaults to Time.now.utc)
+        # @param from_time [Time, nil] Reference time (defaults to Familia.now)
         # @return [Float] Age in days
         # @example
         #   timestamp.days_old    #=> 2.5
@@ -230,17 +231,17 @@ module Familia
         #   is within the same second. Use within? to check this case.
         #
         # @example
-        #   Time.now.older_than?(1.second)    #=> false
+        #   Familia.now.older_than?(1.second)    #=> false
         def older_than?(duration)
-          self < (Time.now.utc.to_f - duration)
+          self < (Familia.now - duration)
         end
 
         # Checks if timestamp is newer than specified duration in the future
         #
         # @example
-        #   Time.now.newer_than?(1.second)    #=> false
+        #   Familia.now.newer_than?(1.second)    #=> false
         def newer_than?(duration)
-          self > (Time.now.utc.to_f + duration)
+          self > (Familia.now + duration)
         end
 
         # Checks if timestamp is within specified duration of now (past or future)
@@ -252,11 +253,11 @@ module Familia
         #   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
+          (self - Familia.now).abs <= duration
         end
       end
 
-      refine ::String do
+      module StringMethods
         # Converts string time representation to seconds
         #
         # @example
@@ -266,14 +267,21 @@ module Familia
         #
         # @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
+          quantity, unit = scan(/([\d.]+)([a-zA-Zμs]+)?/).flatten
+          return nil unless quantity
 
-          q   = q.to_f
-          u ||= 's'
-          q.in_seconds(u)
+          quantity = quantity.to_f
+          unit ||= 's'
+          TimeLiterals.convert_to_seconds(quantity, unit)
         end
       end
+
+      refine ::Numeric do
+        import_methods NumericMethods
+      end
+      refine ::String do
+        import_methods StringMethods
+      end
     end
   end
 end

data/lib/familia/refinements.rb

@@ -1,5 +1,6 @@
 # lib/familia/refinements.rb
 
+require_relative 'refinements/dear_json'
 require_relative 'refinements/logger_trace'
-require_relative 'refinements/snake_case'
+require_relative 'refinements/stylize_words'
 require_relative 'refinements/time_literals'