familia 2.0.0.pre14 → 2.0.0.pre16

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'

data/lib/familia/secure_identifier.rb

@@ -5,41 +5,58 @@ require 'securerandom'
 # Provides a suite of tools for generating and manipulating cryptographically
 # secure identifiers in various formats and lengths.
 module Familia
+  # Cryptographically secure random identifiers.
+  #
+  # Strength tiers
+  # --------------
+  # 256-bit : cryptographic secrets, session tokens, API keys
+  # 128-bit : business/user IDs, product SKUs, non-secret resources
+  #  64-bit : request tracing, log correlation, ephemeral tags
+  #
+  # All methods use `SecureRandom`; collisions are probabilistic and
+  # scale with the number of generated values, not time.
+  #
   module SecureIdentifier
-    # Generates a 256-bit cryptographically secure hexadecimal identifier.
+    # 256-bit identifier – the "full-strength" version.
     #
-    # @return [String] A 64-character hex string representing 256 bits of entropy.
-    # @security Provides ~10^77 possible values, far exceeding UUIDv4's 128 bits.
-    def generate_hex_id
-      SecureRandom.hex(32)
-    end
-
-    # Generates a 64-bit cryptographically secure hexadecimal trace identifier.
+    # Safe for:
+    #   * cryptographic secrets, session tokens, API keys
+    #   * any identifier that must resist brute-force or intentional guessing
     #
-    # @return [String] A 16-character hex string representing 64 bits of entropy.
-    # @note 64 bits provides ~18 quintillion values, sufficient for request tracing.
-    def generate_hex_trace_id
-      SecureRandom.hex(8)
+    # @param base [Integer] 2–36, defaults to 36 for URL-safe chars
+    # @return [String] identifier in specified base, zero-padded to minimum length for 256 bits
+    def generate_id(base = 36)
+      _generate_secure_id(bits: 256, base: base)
     end
 
-    # Generates a cryptographically secure identifier, encoded in the specified base.
-    # By default, this creates a compact, URL-safe base-36 string.
+    # 128-bit identifier – the "lite" version.
     #
-    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
-    # @return [String] A secure identifier.
-    def generate_id(base = 36)
-      target_length = SecureIdentifier.min_length_for_bits(256, base)
-      generate_hex_id.to_i(16).to_s(base).rjust(target_length, '0')
+    # Safe for:
+    #   * ~ 10¹⁵ generated values (collision risk < 10⁻⁹)
+    #   * business/user IDs, product SKUs, non-secret resources
+    #
+    # NOT safe for:
+    #   * security tokens that must resist intentional guessing
+    #
+    # @param base [Integer] 2–36, defaults to 36 for URL-safe chars
+    # @return [String] identifier in specified base, zero-padded to minimum length for 128 bits
+    def generate_lite_id(base = 36)
+      _generate_secure_id(bits: 128, base: base)
     end
 
-    # Generates a short, secure trace identifier, encoded in the specified base.
-    # Suitable for tracing, logging, and other ephemeral use cases.
+    # 64-bit identifier – the "trace" version.
+    #
+    # Safe for:
+    #   * request tracing, log correlation, ephemeral tags
+    #   * up to ~ 10⁹ values (collision risk < 10⁻⁶)
     #
-    # @param base [Integer] The base for encoding the output string (2-36, default: 36).
-    # @return [String] A secure short identifier.
+    # NOT safe for:
+    #   * long-lived identifiers or security contexts
+    #
+    # @param base [Integer] 2–36, defaults to 36 for URL-safe chars
+    # @return [String] identifier in specified base, zero-padded to minimum length for 64 bits
     def generate_trace_id(base = 36)
-      target_length = SecureIdentifier.min_length_for_bits(64, base)
-      generate_hex_trace_id.to_i(16).to_s(base).rjust(target_length, '0')
+      _generate_secure_id(bits: 64, base: base)
     end
 
     # Creates a deterministic 64-bit trace identifier from a longer hex ID.
@@ -68,9 +85,7 @@ module Familia
       target_length = SecureIdentifier.min_length_for_bits(bits, base)
       input_bits = hex_id.length * 4
 
-      unless hex_id.match?(/\A[0-9a-fA-F]+\z/)
-        raise ArgumentError, "Invalid hexadecimal string: #{hex_id}"
-      end
+      raise ArgumentError, "Invalid hexadecimal string: #{hex_id}" unless hex_id.match?(/\A[0-9a-fA-F]+\z/)
 
       if input_bits < bits
         raise ArgumentError, "Input bits (#{input_bits}) cannot be less than desired output bits (#{bits})."
@@ -84,6 +99,23 @@ module Familia
     # Calculates the minimum string length required to represent a given number of
     # bits in a specific numeric base.
     #
+    private
+
+    # Generates a secure identifier with specified bit length and base.
+    #
+    # @private
+    #
+    # @param bits [Integer] The number of bits of entropy (64, 128, or 256).
+    # @param base [Integer] The numeric base (2-36).
+    # @return [String] The generated identifier.
+    def _generate_secure_id(bits:, base:)
+      hex_id = SecureRandom.hex(bits / 8)
+      return hex_id if base == 16
+
+      len = SecureIdentifier.min_length_for_bits(bits, base)
+      hex_id.to_i(16).to_s(base).rjust(len, '0')
+    end
+
     # @private
     #
     # @param bits [Integer] The number of bits of entropy.