optify-config 1.1.1-x86_64-linux → 1.2.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1eb1ffc6d1247d02bab997feac02b34260477f8bd376a7285f88d8f390691a0
-  data.tar.gz: 7434261c974c4542def86b56af9be981cbf38bd6ad87e6b97f9f111180447886
+  metadata.gz: d152a7b0a515813a7bfbffd48b0195be0ed1dbc31ceb3f8c29f58f8f5cef06c4
+  data.tar.gz: 8880f78d7674daf2bd61fa63db3ae50e4b35025d074d178bcc57d6147fe3851b
 SHA512:
-  metadata.gz: 12ed18ab665cc2bf1c86132707bfa2a7f4553a2e3e17923d5499bab66c700ed22c7fdc5d25022d8549c07f540648e15a41611ed9077bd32c9a5cf94f728dc0c0
-  data.tar.gz: 1adc408eb310c6efde2d8f30c9cbf742d4f789f6f5ced4bfb37ad0dc6c8b3b0a830878e9dd3b080ef8894e904703ae646740be9e7436131f198f6ef9aafe5e69
+  metadata.gz: 4f525f2ad659cfc4890225b06d6c233c83e6c7382a5376aca1d2ae8317db08700bc8e7337c2e82321373903bb0cef0e661064292ceb6b46beac0905feaa818f2
+  data.tar.gz: 5f23075d85e854bbb1845dee8ccb435c2d5045321486cdba8ad27ddb1f592be69db4d14d7966a9c3a168299341d025f118b78884e237b52aa55756978af4fe69

data/lib/optify.rb

@@ -3,6 +3,7 @@
 
 # The implementation to use directly Ruby and with types declared.
 require_relative 'optify_ruby/implementation'
+require_relative 'optify_ruby/watcher_implementation'
 
 # The implementation in Rust which redefines some methods.
 # This yields some warnings, but we should redeclare the methods in Ruby to help with type checking anyway.

data/lib/optify_ruby/implementation.rb

@@ -7,6 +7,7 @@ require 'sorbet-runtime'
 
 require_relative './base_config'
 require_relative './options_metadata'
+require_relative './provider_module'
 
 # Tools for working with configurations declared in files.
 module Optify
@@ -17,92 +18,26 @@ module Optify
 
   # Provides configurations based on keys and enabled feature names.
   class OptionsProvider
-    extend T::Sig
+    include ProviderModule
+
+    # TODO: Find a better way to proxy the methods with copying the parameters.
 
     #: -> Hash[String, OptionsMetadata]
     def features_with_metadata
-      return @features_with_metadata if @features_with_metadata
-
-      result = JSON.parse(features_with_metadata_json)
-      result.each do |key, value|
-        result[key] = OptionsMetadata.from_hash(value)
-      end
-      result.freeze
-
-      @features_with_metadata = T.let(result, T.nilable(T::Hash[String, OptionsMetadata]))
-      result
-    end
-
-    #: (String canonical_feature_name) -> Optify::OptionsMetadata?
-    def get_feature_metadata(canonical_feature_name)
-      metadata_json = get_feature_metadata_json(canonical_feature_name)
-      return nil if metadata_json.nil?
-
-      OptionsMetadata.from_hash(JSON.parse(metadata_json))
+      _features_with_metadata
     end
 
-    # Fetches options based on the provided key and feature names.
-    #
-    # @param key The key to fetch options for.
-    # @param feature_names The enabled feature names to use to build the options.
-    # @param config_class The class of the configuration to return.
-    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
-    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
-    # @param preferences The preferences to use when getting options.
-    # @return The options.
     #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
     def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil)
-      return get_options_with_cache(key, feature_names, config_class, cache_options, preferences) if cache_options
-
-      unless config_class.respond_to?(:from_hash)
-        raise NotImplementedError,
-              "The provided config class must implement `from_hash` as a class method
-              in order to be converted.
-              Recommended: extend `Optify::BaseConfig`."
-      end
-
-      options_json = if preferences
-                       get_options_json_with_preferences(key, feature_names, preferences)
-                     else
-                       get_options_json(key, feature_names)
-                     end
-      hash = JSON.parse(options_json)
-      T.unsafe(config_class).from_hash(hash)
+      _get_options(key, feature_names, config_class, cache_options, preferences)
     end
 
     # (Optional) Eagerly initializes the cache.
     # @return [OptionsProvider] `self`.
     #: -> OptionsProvider
     def init
-      @cache = T.let({}, T.nilable(T::Hash[T.untyped, T.untyped]))
+      _init
       self
     end
-
-    private
-
-    NOT_FOUND_IN_CACHE_SENTINEL = Object.new
-
-    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, Optify::CacheOptions _cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
-    def get_options_with_cache(key, feature_names, config_class, _cache_options, preferences = nil)
-      # Cache directly in Ruby instead of Rust because:
-      # * Avoid any possible conversion overhead.
-      # * Memory management: probably better to do it in Ruby for a Ruby app and avoid memory in Rust.
-      init unless @cache
-      unless preferences&.skip_feature_name_conversion
-        # When there are just a few names, then it can be faster to convert them one by one in a loop to avoid working with an array in Rust.
-        # When there are over 7 names, then it is faster to convert them with one call to Rust.
-        feature_names = get_canonical_feature_names(feature_names)
-      end
-
-      cache_key = [key, feature_names, config_class]
-      result = @cache&.fetch(cache_key, NOT_FOUND_IN_CACHE_SENTINEL)
-      return result unless result.equal?(NOT_FOUND_IN_CACHE_SENTINEL)
-
-      preferences ||= GetOptionsPreferences.new
-      preferences.skip_feature_name_conversion = true
-      result = get_options(key, feature_names, config_class, nil, preferences)
-
-      T.must(@cache)[cache_key] = result
-    end
   end
 end

data/lib/optify_ruby/provider_module.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'sorbet-runtime'
+
+module Optify
+  # @!visibility private
+  module ProviderModule
+    extend T::Sig
+
+    #: (Array[String] feature_names) -> Array[String]
+    def get_canonical_feature_names(feature_names)
+      # Try to optimize a typical case where there are just a few features.
+      # Ideally in production, a single feature that imports many other features is used for the most common scenario.
+      # Benchmarks show that it is faster to use a loop than to call the Rust implementation which involves making a `Vec<String>` and returning a `Vec<String>`.
+      if feature_names.length < 4
+        feature_names.map { |feature_name| get_canonical_feature_name(feature_name) }
+      else
+        _get_canonical_feature_names(feature_names)
+      end
+    end
+
+    #: (String canonical_feature_name) -> Optify::OptionsMetadata?
+    def get_feature_metadata(canonical_feature_name)
+      metadata_json = get_feature_metadata_json(canonical_feature_name)
+      return nil if metadata_json.nil?
+
+      OptionsMetadata.from_hash(JSON.parse(metadata_json))
+    end
+
+    private
+
+    #: -> Hash[String, OptionsMetadata]
+    def _features_with_metadata
+      return @features_with_metadata if @features_with_metadata
+
+      result = JSON.parse(features_with_metadata_json)
+      result.each do |key, value|
+        result[key] = OptionsMetadata.from_hash(value)
+      end
+      result.freeze
+
+      @features_with_metadata = T.let(result, T.nilable(T::Hash[String, OptionsMetadata]))
+      result
+    end
+
+    # Fetches options based on the provided key and feature names.
+    #
+    # @param key The key to fetch options for.
+    # @param feature_names The enabled feature names to use to build the options.
+    # @param config_class The class of the configuration to return.
+    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
+    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
+    # @param preferences The preferences to use when getting options.
+    # @return The options.
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def _get_options(key, feature_names, config_class, cache_options = nil, preferences = nil)
+      return get_options_with_cache(key, feature_names, config_class, cache_options, preferences) if cache_options
+
+      unless config_class.respond_to?(:from_hash)
+        Kernel.raise NotImplementedError,
+                     "The provided config class must implement `from_hash` as a class method
+              in order to be converted.
+              Recommended: extend `Optify::BaseConfig`."
+      end
+
+      options_json = if preferences
+                       get_options_json_with_preferences(key, feature_names, preferences)
+                     else
+                       get_options_json(key, feature_names)
+                     end
+      hash = JSON.parse(options_json)
+      T.unsafe(config_class).from_hash(hash)
+    end
+
+    #: -> void
+    def _init
+      @cache = T.let({}, T.nilable(T::Hash[T.untyped, T.untyped]))
+      @features_with_metadata = T.let(nil, T.nilable(T::Hash[String, OptionsMetadata]))
+    end
+
+    NOT_FOUND_IN_CACHE_SENTINEL = Object.new
+
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, Optify::CacheOptions _cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def get_options_with_cache(key, feature_names, config_class, _cache_options, preferences = nil)
+      # Cache directly in Ruby instead of Rust because:
+      # * Avoid any possible conversion overhead.
+      # * Memory management: probably better to do it in Ruby for a Ruby app and avoid memory in Rust.
+      init unless @cache
+      unless preferences&.skip_feature_name_conversion
+        # When there are just a few names, then it can be faster to convert them one by one in a loop to avoid working with an array in Rust.
+        # When there are over 7 names, then it is faster to convert them with one call to Rust.
+        feature_names = get_canonical_feature_names(feature_names)
+      end
+
+      cache_key = [key, feature_names, config_class]
+      result = @cache&.fetch(cache_key, NOT_FOUND_IN_CACHE_SENTINEL)
+      return result unless result.equal?(NOT_FOUND_IN_CACHE_SENTINEL)
+
+      preferences ||= GetOptionsPreferences.new
+      preferences.skip_feature_name_conversion = true
+      result = get_options(key, feature_names, config_class, nil, preferences)
+
+      T.must(@cache)[cache_key] = result
+    end
+  end
+end

data/lib/optify_ruby/watcher_implementation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# typed: strict
+
+require 'json'
+
+require 'sorbet-runtime'
+
+require_relative './base_config'
+require_relative './implementation'
+require_relative './options_metadata'
+require_relative './provider_module'
+
+module Optify
+  # @!visibility private
+  class OptionsWatcher
+    include ProviderModule
+
+    # TODO: Find a better way to proxy the methods with copying the parameters.
+
+    #: -> Hash[String, OptionsMetadata]
+    def features_with_metadata
+      _check_cache
+      _features_with_metadata
+    end
+
+    #: [Config] (String key, Array[String] feature_names, Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+    def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil)
+      _check_cache if cache_options
+
+      _get_options(key, feature_names, config_class, cache_options, preferences)
+    end
+
+    # (Optional) Eagerly initializes the cache.
+    # @return [OptionsWatcher] `self`.
+    #: -> OptionsWatcher
+    def init
+      _init
+      @cache_creation_time = T.let(Time.now, T.nilable(Time))
+      self
+    end
+
+    private
+
+    #: -> void
+    def _check_cache
+      return if @cache_creation_time && @cache_creation_time > last_modified
+
+      # The cache is not setup or it is out of date.
+      init
+    end
+  end
+end

data/rbi/optify.rbi

@@ -49,8 +49,10 @@ module Optify
     def skip_feature_name_conversion; end
   end
 
-  # Provides configurations based on keys and enabled feature names.
-  class OptionsProvider
+  # A registry of features that provides configurations.
+  class OptionsRegistry
+    abstract!
+
     # @return All of the canonical feature names.
     sig { returns(T::Array[String]) }
     def features; end
@@ -65,7 +67,12 @@ module Optify
         .returns(String)
     end
     def get_all_options_json(feature_names, preferences); end
+  end
 
+  # A module only for internal use that provides the methods to help implement providers.
+  # Some of the methods shown within this module are implemented in Rust
+  # and are declared in this common module to avoid duplicate declarations in different classes.
+  module ProviderModule
     # Map an alias or canonical feature name (perhaps derived from a file name) to a canonical feature name.
     # Canonical feature names map to themselves.
     #
@@ -76,6 +83,7 @@ module Optify
 
     # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
     # Canonical feature names map to themselves.
+    # This implementation may do an optimization for small arrays.
     #
     # @param feature_names The names of aliases or features.
     # @return The canonical feature names.
@@ -86,28 +94,6 @@ module Optify
     sig { params(canonical_feature_name: String).returns(T.nilable(OptionsMetadata)) }
     def get_feature_metadata(canonical_feature_name); end
 
-    # Fetches options based on the provided key and feature names.
-    #
-    # @param key The key to fetch options for.
-    # @param feature_names The enabled feature names to use to build the options.
-    # @param config_class The class of the configuration to return.
-    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
-    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
-    # @param preferences The preferences to use when getting options.
-    # @return The options.
-    sig do
-      type_parameters(:Config)
-        .params(
-          key: String,
-          feature_names: T::Array[String],
-          config_class: T::Class[T.type_parameter(:Config)],
-          cache_options: T.nilable(CacheOptions),
-          preferences: T.nilable(Optify::GetOptionsPreferences)
-        )
-        .returns(T.type_parameter(:Config))
-    end
-    def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil); end
-
     # Fetches options in JSON format based on the provided key and feature names.
     #
     # @param key [String] the key to fetch options for.
@@ -128,13 +114,17 @@ module Optify
     end
     def get_options_json_with_preferences(key, feature_names, preferences); end
 
-    # (Optional) Eagerly initializes the cache.
-    # @return [OptionsProvider] `self`.
-    sig { returns(OptionsProvider) }
-    def init; end
-
     private
 
+    # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+    # Canonical feature names map to themselves.
+    # This implementation calls the Rust implementation directly.
+    #
+    # @param feature_names The names of aliases or features.
+    # @return The canonical feature names.
+    sig { params(feature_names: T::Array[String]).returns(T::Array[String]) }
+    def _get_canonical_feature_names(feature_names); end
+
     # @return The metadata for the feature.
     sig { params(canonical_feature_name: String).returns(T.nilable(String)) }
     def get_feature_metadata_json(canonical_feature_name); end
@@ -142,6 +132,38 @@ module Optify
     # @return All of the keys and values for the the features.
     sig { returns(String) }
     def features_with_metadata_json; end
+
+    # Fetches options based on the provided key and feature names.
+    #
+    # @param key The key to fetch options for.
+    # @param feature_names The enabled feature names to use to build the options.
+    # @param config_class The class of the configuration to return.
+    # It is recommended to use a class that extends `Optify::BaseConfig` because it implements `from_hash`.
+    # @param cache_options Set this if caching is desired. Only very simple caching is supported for now.
+    # @param preferences The preferences to use when getting options.
+    # @return The options.
+    sig do
+      type_parameters(:Config)
+        .params(
+          key: String,
+          feature_names: T::Array[String],
+          config_class: T::Class[T.type_parameter(:Config)],
+          cache_options: T.nilable(CacheOptions),
+          preferences: T.nilable(Optify::GetOptionsPreferences)
+        )
+        .returns(T.type_parameter(:Config))
+    end
+    def get_options(key, feature_names, config_class, cache_options = nil, preferences = nil); end
+
+    # (Optional) Eagerly initializes the cache.
+    # @return `self`.
+    sig { returns(T.self_type) }
+    def init; end
+  end
+
+  # Provides configurations based on keys and enabled feature names.
+  class OptionsProvider < OptionsRegistry
+    include ProviderModule
   end
 
   # A builder for creating an `OptionsProvider` instance.
@@ -157,4 +179,30 @@ module Optify
     sig { returns(OptionsProvider) }
     def build; end
   end
+
+  # Like `OptionsProvider` but also watches for changes to the files and reloads the options.
+  class OptionsWatcher < OptionsRegistry
+    include ProviderModule
+
+    # @return [Time] Returns the time when the provider was finished building.
+    sig { returns(Time) }
+    def last_modified; end
+  end
+
+  # A builder for creating an `OptionsWatcher` instance.
+  #
+  # This builder is kept separate from the `OptionsProviderBuilder`
+  # in order to keep `OptionsProviderBuilder` and `OptionsProvider` as simple and efficient as possible for production use.
+  class OptionsWatcherBuilder
+    # Adds a directory to watch for changes.
+    #
+    # @param path [String] The path of the directory to add.
+    # @return [OptionsWatcherBuilder] `self`.
+    sig { params(path: String).returns(OptionsWatcherBuilder) }
+    def add_directory(path); end
+
+    # @return [OptionsWatcher] A newly built `OptionsWatcher`.
+    sig { returns(OptionsWatcher) }
+    def build; end
+  end
 end

data/sig/optify.rbs

@@ -40,8 +40,8 @@ class Optify::GetOptionsPreferences
   def skip_feature_name_conversion: () -> bool
 end
 
-# Provides configurations based on keys and enabled feature names.
-class Optify::OptionsProvider
+# A registry of features that provides configurations.
+class Optify::OptionsRegistry
   # @return All of the canonical feature names.
   def features: () -> ::Array[String]
 
@@ -49,7 +49,12 @@ class Optify::OptionsProvider
   def features_with_metadata: () -> ::Hash[String, OptionsMetadata]
 
   def get_all_options_json: (::Array[String] feature_names, GetOptionsPreferences preferences) -> String
+end
 
+# A module only for internal use that provides the methods to help implement providers.
+# Some of the methods shown within this module are implemented in Rust
+# and are declared in this common module to avoid duplicate declarations in different classes.
+module Optify::ProviderModule
   # Map an alias or canonical feature name (perhaps derived from a file name) to a canonical feature name.
   # Canonical feature names map to themselves.
   #
@@ -59,6 +64,7 @@ class Optify::OptionsProvider
 
   # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
   # Canonical feature names map to themselves.
+  # This implementation may do an optimization for small arrays.
   #
   # @param feature_names The names of aliases or features.
   # @return The canonical feature names.
@@ -67,8 +73,6 @@ class Optify::OptionsProvider
   # @return The metadata for the feature.
   def get_feature_metadata: (String canonical_feature_name) -> OptionsMetadata?
 
-  def get_options: [Config] (String key, ::Array[String] feature_names, T::Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
-
   # Fetches options in JSON format based on the provided key and feature names.
   #
   # @param key [String] the key to fetch options for.
@@ -78,15 +82,30 @@ class Optify::OptionsProvider
 
   def get_options_json_with_preferences: (String key, ::Array[String] feature_names, GetOptionsPreferences preferences) -> String
 
-  # (Optional) Eagerly initializes the cache.
-  # @return [OptionsProvider] `self`.
-  def init: () -> OptionsProvider
+  # Map aliases or canonical feature names (perhaps derived from a file names) to the canonical feature names.
+  # Canonical feature names map to themselves.
+  # This implementation calls the Rust implementation directly.
+  #
+  # @param feature_names The names of aliases or features.
+  # @return The canonical feature names.
+  def _get_canonical_feature_names: (::Array[String] feature_names) -> ::Array[String]
 
   # @return The metadata for the feature.
   def get_feature_metadata_json: (String canonical_feature_name) -> String?
 
   # @return All of the keys and values for the the features.
   def features_with_metadata_json: () -> String
+
+  def get_options: [Config] (String key, ::Array[String] feature_names, T::Class[Config] config_class, ?CacheOptions? cache_options, ?Optify::GetOptionsPreferences? preferences) -> Config
+
+  # (Optional) Eagerly initializes the cache.
+  # @return `self`.
+  def init: () -> self
+end
+
+# Provides configurations based on keys and enabled feature names.
+class Optify::OptionsProvider < OptionsRegistry
+  include ProviderModule
 end
 
 # A builder for creating an `OptionsProvider` instance.
@@ -100,3 +119,26 @@ class Optify::OptionsProviderBuilder
   # @return [OptionsProvider] A newly built `OptionsProvider`.
   def build: () -> OptionsProvider
 end
+
+# Like `OptionsProvider` but also watches for changes to the files and reloads the options.
+class Optify::OptionsWatcher < OptionsRegistry
+  include ProviderModule
+
+  # @return [Time] Returns the time when the provider was finished building.
+  def last_modified: () -> Time
+end
+
+# A builder for creating an `OptionsWatcher` instance.
+#
+# This builder is kept separate from the `OptionsProviderBuilder`
+# in order to keep `OptionsProviderBuilder` and `OptionsProvider` as simple and efficient as possible for production use.
+class Optify::OptionsWatcherBuilder
+  # Adds a directory to watch for changes.
+  #
+  # @param path [String] The path of the directory to add.
+  # @return [OptionsWatcherBuilder] `self`.
+  def add_directory: (String path) -> OptionsWatcherBuilder
+
+  # @return [OptionsWatcher] A newly built `OptionsWatcher`.
+  def build: () -> OptionsWatcher
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optify-config
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: x86_64-linux
 authors:
 - Justin D. Harris
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-04-11 00:00:00.000000000 Z
+date: 2025-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -108,6 +108,8 @@ files:
 - lib/optify_ruby/base_config.rb
 - lib/optify_ruby/implementation.rb
 - lib/optify_ruby/options_metadata.rb
+- lib/optify_ruby/provider_module.rb
+- lib/optify_ruby/watcher_implementation.rb
 - rbi/optify.rbi
 - sig/optify.rbs
 homepage: https://github.com/juharris/optify