super_settings 2.3.1 → 2.4.1

data/lib/super_settings/rest_api.rb

@@ -16,12 +16,14 @@ module SuperSettings
       #       key: string,
       #       value: object,
       #       value_type: string,
-      #       description string,
+      #       description: string,
       #       created_at: iso8601 string,
       #       updated_at: iso8601 string
       #     },
       #     ...
       #   ]
+      #
+      # @return [Hash] hash with settings array
       def index
         settings = Setting.active.reject(&:deleted?).sort_by(&:key)
         {settings: settings.collect(&:as_json)}
@@ -29,6 +31,7 @@ module SuperSettings
 
       # Get a setting by id.
       #
+      # @param key [String] setting key
       # @example
       #   GET /setting
       #
@@ -41,10 +44,12 @@ module SuperSettings
       #     key: string,
       #     value: object,
       #     value_type: string,
-      #     description string,
+      #     description: string,
       #     created_at: iso8601 string,
       #     updated_at: iso8601 string
       #   }
+      #
+      # @return [Hash, nil] setting hash or nil if not found
       def show(key)
         setting = Setting.find_by_key(key)
         setting.as_json if setting && !setting.deleted?
@@ -52,6 +57,8 @@ module SuperSettings
 
       # The update operation uses a transaction to atomically update all settings.
       #
+      # @param settings_params [Array] array of setting parameter hashes
+      # @param changed_by [String] identifier for who made the changes
       # @example
       #   POST /settings
       #
@@ -81,6 +88,8 @@ module SuperSettings
       #   or
       #
       #   {success: false, errors: {key => [string], ...}}
+      #
+      # @return [Hash] result hash with success status and any errors
       def update(settings_params, changed_by = nil)
         all_valid, settings = Setting.bulk_update(Array(settings_params), changed_by)
         if all_valid
@@ -98,6 +107,9 @@ module SuperSettings
 
       # Return the history of the setting.
       #
+      # @param key [String] setting key
+      # @param limit [Integer] number of history items to return
+      # @param offset [Integer] index to start fetching items from (most recent items are first)
       # @example
       #   GET /setting/history
       #
@@ -121,6 +133,8 @@ module SuperSettings
       #     previous_page_params: hash,
       #     next_page_params: hash
       #   }
+      #
+      # @return [Hash, nil] history hash or nil if setting not found
       def history(key, limit: nil, offset: 0)
         setting = Setting.find_by_key(key)
         return nil unless setting
@@ -162,12 +176,15 @@ module SuperSettings
       #   {
       #     last_updated_at: iso8601 string
       #   }
+      #
+      # @return [Hash] hash with the last updated timestamp
       def last_updated_at
         {last_updated_at: Setting.last_updated_at.utc.iso8601(6)}
       end
 
       # Return settings that have been updated since a specified timestamp.
       #
+      # @param time [Time, String] timestamp to check for updates since
       # @example
       #   GET /updated_since
       #
@@ -181,12 +198,14 @@ module SuperSettings
       #       key: string,
       #       value: object,
       #       value_type: string,
-      #       description string,
+      #       description: string,
       #       created_at: iso8601 string,
       #       updated_at: iso8601 string
       #     },
       #     ...
       #   ]
+      #
+      # @return [Hash] hash with settings array
       def updated_since(time)
         time = Coerce.time(time)
         settings = Setting.updated_since(time).reject(&:deleted?)

data/lib/super_settings/setting.rb

@@ -9,6 +9,7 @@ module SuperSettings
   # ships with storage engines for ActiveRecord, Redis, and HTTP (microservice). See the SuperSettings::Storage
   # class for more details.
   class Setting
+    # Cache key used for storing the last updated timestamp.
     LAST_UPDATED_CACHE_KEY = "SuperSettings.last_updated_at"
 
     STRING = "string"
@@ -266,6 +267,7 @@ module SuperSettings
           setting = changed[key] || Setting.find_by_key(key)
           unless setting
             next if Coerce.present?(setting_params["delete"])
+
             setting = Setting.new(key: setting_params["key"])
           end
 
@@ -545,6 +547,7 @@ module SuperSettings
 
     # Serialize to a hash that is used for rendering JSON responses.
     #
+    # @param options [Hash] options for JSON serialization (unused but maintained for compatibility)
     # @return [Hash]
     def as_json(options = nil)
       attributes = {
@@ -561,6 +564,7 @@ module SuperSettings
 
     # Serialize to a JSON string.
     #
+    # @param options [Hash] options to pass to JSON generation
     # @return [String]
     def to_json(options = nil)
       as_json.to_json(options)

data/lib/super_settings/storage/http_storage.rb

@@ -35,15 +35,13 @@ module SuperSettings
         # Add headers to this hash to add them to all requests to the SuperSettings REST API.
         #
         # @example
-        #
-        # SuperSettings::HttpStorage.headers["Authorization"] = "Bearer 12345"
+        #   SuperSettings::HttpStorage.headers["Authorization"] = "Bearer 12345"
         attr_reader :headers
 
         # Add query parameters to this hash to add them to all requests to the SuperSettings REST API.
         #
         # @example
-        #
-        # SuperSettings::HttpStorage.query_params["access_token"] = "12345"
+        #   SuperSettings::HttpStorage.query_params["access_token"] = "12345"
         attr_reader :query_params
 
         def all

data/lib/super_settings/storage/redis_storage.rb

@@ -35,6 +35,7 @@ module SuperSettings
           def find_all_by_key(key:, offset: 0, limit: nil)
             end_index = (limit.nil? ? -1 : offset + limit - 1)
             return [] unless end_index >= -1
+
             payloads = RedisStorage.with_redis { |redis| redis.lrange("#{HISTORY_KEY_PREFIX}.#{key}", offset, end_index) }
             payloads.collect do |json|
               record = new(JSON.parse(json))
@@ -112,6 +113,7 @@ module SuperSettings
         def find_by_key(key)
           json = with_redis { |redis| redis.hget(SETTINGS_KEY, key) }
           return nil unless json
+
           record = load_from_json(json)
           record unless record.deleted?
         end
@@ -123,6 +125,7 @@ module SuperSettings
         def last_updated_at
           result = with_redis { |redis| redis.zrevrange(UPDATED_KEY, 0, 1, withscores: true).first }
           return nil unless result
+
           time_at_microseconds(result[1])
         end
 

data/lib/super_settings/storage/test_storage.rb

@@ -50,6 +50,7 @@ module SuperSettings
         def find_by_key(key)
           attributes = settings[key]
           return nil unless attributes
+
           setting = new(attributes)
           setting.send(:set_persisted!)
           setting unless setting.deleted?

data/lib/super_settings/time_precision.rb

@@ -4,24 +4,42 @@ module SuperSettings
   # Helper class for truncating timestamps to a specific precision. This is used by storage engines
   # to ensure that timestamps are stored and compared with the same precision.
   class TimePrecision
+    # The time value with applied precision.
     attr_reader :time
 
+    # Create a new TimePrecision object.
+    #
+    # @param time [Time, Numeric] the time to apply precision to
+    # @param precision [Symbol] the precision level (:microsecond or :millisecond)
+    # @raise [ArgumentError] if precision is not valid
     def initialize(time, precision = :microsecond)
       raise ArgumentError.new("Invalid precision: #{precision}") unless valid_precision?(precision)
 
       @time = time_with_precision(time.to_f, precision) if time
     end
 
+    # Convert the time to a float.
+    #
+    # @return [Float] the time as a floating point number
     def to_f
       @time.to_f
     end
 
     private
 
+    # Check if the precision value is valid.
+    #
+    # @param precision [Symbol] the precision to validate
+    # @return [Boolean] true if precision is valid
     def valid_precision?(precision)
       [:microsecond, :millisecond].include?(precision)
     end
 
+    # Apply the specified precision to a timestamp.
+    #
+    # @param timestamp [Float] the timestamp to apply precision to
+    # @param precision [Symbol] the precision level
+    # @return [Time] the time with applied precision
     def time_with_precision(timestamp, precision)
       usec = (timestamp % 1) * 1_000_000.0
       if precision == :millisecond

data/lib/super_settings.rb

@@ -23,6 +23,7 @@ module SuperSettings
   autoload :HttpClient, "super_settings/http_client"
   autoload :VERSION, "super_settings/version"
 
+  # Default number of seconds between cache refresh checks.
   DEFAULT_REFRESH_INTERVAL = 5.0
 
   @local_cache = LocalCache.new(refresh_interval: DEFAULT_REFRESH_INTERVAL)
@@ -41,7 +42,7 @@ module SuperSettings
       Coerce.string(val)
     end
 
-    # Alias for {#get} to allow using the [] operator to get a setting value.
+    # Alias for {.get} to allow using the [] operator to get a setting value.
     #
     # @param key [String, Symbol]
     # @return [String]
@@ -107,6 +108,7 @@ module SuperSettings
       val = context_setting(key)
       val = default if val.nil?
       return nil if val.nil?
+
       Array(val).collect { |v| v&.to_s }
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: super_settings
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.1
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -31,6 +31,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE.txt
 - README.md