configx 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52b7bdd6e023a3ea747b90c4ef46061484bbe831bab45bf121e51f4352f8ca1a
-  data.tar.gz: 87ec00bce9b86453747a1f36579b5c2fb9ee6b7440c68681febe75799e425f95
+  metadata.gz: 16db5f1190ac4fbe24e85387f7b3ca7bee509c7e6708d0e637b48eb2303bf3c9
+  data.tar.gz: b985146110a368f9dc5cab2aa981fff7b12ca0d39a544a43448b9da9cff26241
 SHA512:
-  metadata.gz: 8e1143144c3f21e83c3d5059bb40bdb0e5921c2788a5d6d149dab1e12e8dfd79990a78e0066e2a5a1b9f94c43585a00ab8136814fadb1aa25d6fe3f398cf8f17
-  data.tar.gz: 92755126398c1c3a53846661bd5a8b53606a84c81984897a51a2c460c1cf4a44cd10cc63397323e5e246cee1feb23d689132b168614158ea5cb3c221343beecf
+  metadata.gz: e4397f851488af93b623e1c61090e7d1ecfb790ed800e1fd2667c89bd90de72a5ad8d66ffecf3cf44318a11fafe4764ef1e69d5f6d14c4c7c75f1d2694ff0ee0
+  data.tar.gz: ad768e3b2a8e4fe5f9da813ea959f063b69899637c1cf6550b064bf367fa2ac76f863befc26ac090ced67e8b980e040ba98e73a99ad4491c4e07a2b0ee6343f1

data/README.md

@@ -1,31 +1,34 @@
 # ⚙️ConfigX
 
-ConfigX is a simple configuration library that you can use with your application or libraries.
-
-ConfigX is NOT that kind of library that allows you configuring any Ruby object, instead
-it takes a different approach. It reads configuration from YAML files and environment variables
-and load it into a ruby object. It's highly influenced by the [config] gem, but it does
-not define a global objects and allows you having multiple independent configurations.
+ConfigX is a lightweight configuration library that helps you manage settings for applications or libraries. 
+Unlike other configuration libraries, ConfigX does not allow configuring arbitrary Ruby objects. Instead, 
+it focuses on loading configuration from YAML files and environment variables into structured Ruby objects. 
+Inspired by the [config] gem, ConfigX avoids defining global objects and supports multiple 
+independent configurations.
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+To install, add the gem to your Gemfile:
 
-    $ bundle add configx
+```bash
+$ bundle add configx
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or, if you’re not using Bundler:
 
-    $ gem install configx
+```bash
+$ gem install configx
+```
 
 ## Usage
 
-Start using the library as simple as loading configuration from default locations:
+To load configuration from the default locations, use:
 
 ```ruby
 config = ConfigX.load
 ```
 
-It loads configuration from the following locations in the specified order:
+This loads configuration from the following sources in order:
 
 1. `config/settings.yml`
 2. `config/settings/production.yml`
@@ -33,7 +36,7 @@ It loads configuration from the following locations in the specified order:
 4. `config/settings/production.local.yml`
 5. Environment variables
 
-All the configuration source are merged an intuitive way. For instance, 
+The configuration is merged in an intuitive way, with environment variables taking precedence. For example: 
 
 * **config/settings.yml**
 
@@ -59,18 +62,18 @@ api:
 export SETTINGS__API__ACCESS_TOKEN=foobar
 ```
 
-The resulting configuration will be:
+Results in:
 
 ```ruby
 config = ConfigX.load
 config.api.enabled # => true
 config.api.endpoint # => "https://example.com"
-config.api.pretty_print # => "foobar"
+config.api.access_token # => "foobar"
 ```
 
 ### Customizing Configuration
 
-You can customize the configuration by passing optional arguments to the `load` method:
+You can customize how configurations are loaded:
 
 ```ruby
 ConfigX.load(
@@ -83,25 +86,26 @@ ConfigX.load(
 )
 ```
 
-The first four options, `env` (positional), `dir_name`, `file_name`, and `config_root` are used to specify 
-the configuration files to read:
+Explanation of options:
+
+* `env`, `dir_name`, `file_name`, and `config_root` specify where to look for configuration files.
+
+In this example ConfigX will look for configuration files in the following order:
 
 1. `{config_root}/{file_name}.yml`
 2. `{config_root}/{file_name}/{env}.yml`
 3. `{config_root}/{file_name}.local.yml`
 4. `{config_root}/{file_name}/{env}.local.yml`
 
+* `env_prefix` and `env_separator` define how environment variables map to configuration keys.
 
-The `env_prefix` and `env_separator` options are used to specify how the environment variables should be constructed. In
-the above example, they start from `SETTINGS` and use `__` as a separator. 
-
-For instance, the following environment variable: 
+For example, with the following environment variable:
 
 ```
 export SETTINGS__API__ACCESS_TOKEN=foobar
 ```
 
-corresponds to the following configuration:
+ConfigX loads it into:
 
 ```yaml
 ---
@@ -109,65 +113,107 @@ api:
   access_token: foobar
 ```
 
-You can also pass boolean value to environment variables using convenient YAML syntax:
+### Environment Variable Parsing
+
+ConfigX automatically parses environment variable values and converts them to the appropriate types where possible. 
+It handles strings, booleans, numbers, and even arrays. The following types are supported:
+
+#### Booleans:
 
-```sh
+```bash
 export SETTINGS__API__ENABLED=true
 export SETTINGS__API__ENABLED=false
 export SETTINGS__API__ENABLED=on
 export SETTINGS__API__ENABLED=off
 ```
 
-Environment variables have the highest priority and override the values from the configuration files. 
+These values will be parsed into their corresponding boolean types (`true` or `false`):
 
-### Builder Interface
+```ruby 
+config.api.enabled # => true or false
+```
 
-When you don't need to load configuration from the predefined default locations, you can use the builder interface
-which enables you to load configuration from any source:
+#### Numbers:
+
+```bash
+export SETTINGS__API__RETRY_COUNT=5
+export SETTINGS__API__TIMEOUT=30.5
+```
 
-1. Plain ruby Hash
+Numeric values will be parsed as either integers or floats:
 
 ```ruby 
-config = ConfigX.builder
-  .add_source({api: {enabled: true}})
-  .load
+config.api.retry_count # => 5
+config.api.timeout # => 30.5
+```
 
-config.api.enabled # => true
+
+#### Arrays:
+
+Arrays can be specified by using comma-separated values:
+
+```bash 
+export SETTINGS__API__SERVERS='["server1","server2","server3"]'
 ```
 
-2. YAML file
+This will be parsed as an array:
 
 ```ruby
-config = ConfigX.builder
-  .add_source('config/settings.yml')
-  .load
+config.api.servers # => ["server1", "server2", "server3"]
 ```
 
-3. Environment variables
 
-```ruby
-config = ConfigX.builder
-  .add_source(ENV, prefix: "SETTINGS", separator: "__")
-  .load
+#### Strings:
+
+Regular string values remain unchanged:
+
+```bash
+export SETTINGS__API__ACCESS_TOKEN="my_secret_token"
 ```
 
-You can also use the builder interface to load configuration from multiple sources:
+This will simply be loaded as a string:
 
 ```ruby
-config = ConfigX.builder
-  .add_source({api: {enabled: true}})
-  .add_source('config/settings.yml')
-  .add_source(ENV, prefix: "SETTINGS", separator: "__")
-  .load
+config.api.access_token # => "my_secret_token"
 ```
 
-Sometimes you may want to just load configuration from a single source, for example, from for testing purposes:
+Environment variables have the highest precedence and will override values from YAML configuration files. 
+This ensures that any environment-specific settings can be applied without modifying the configuration 
+files themselves.
+
+### Loading Single Sources
+
+To load configuration from a specific source (e.g., during testing):
 
 ```ruby
 config = ConfigX.from({api: {enabled: true}})
 config.api.enabled # => true
 ```
 
+### Typed Config 
+
+ConfigX supports typed configurations using `ConfigX::Config`, which leverages [dry-struct]:
+
+```ruby 
+class Config < ConfigX::Config
+  attribute :api do 
+    attribute :enabled, Types::Bool.default(false)
+    attribute :endpoint, Types::String
+    attribute :access_token, Types::String
+  end
+end 
+```
+
+Load the typed configuration with:
+
+```ruby
+config = ConfigX.load(config_class: Config)
+config.api.enabled #=> true
+config.api.endpoint #=> "https://example.com"
+```
+
+Typed configurations enforce structure and type-checking.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -183,3 +229,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/bolsha
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 [config]: https://rubygems.org/gems/config
+[dry-struct]: https://dry-rb.org/gems/dry-struct/

data/lib/config_x/builder.rb

@@ -5,6 +5,11 @@ require "deep_merge/core"
 module ConfigX
   class Builder
     class << self
+      # Creates a source object based on the type of the input.
+      #
+      # @param source [Source, Hash, String, Pathname, ENV] the source input
+      # @param args [Hash] additional arguments for the source
+      # @return [Source]
       def source(source, **args)
         case source
         in Source then source
@@ -15,10 +20,11 @@ module ConfigX
         end
       end
 
+      # Loads the configuration.
+      #
+      # @return [UntypedConfig]
       # @see #initialize
-      def load(...)
-        new(...).load
-      end
+      def load(...) = new.load(...)
     end
 
     # @example
@@ -31,17 +37,18 @@ module ConfigX
 
     attr_reader :sources
 
+    # Adds a source to the builder.
+    #
+    # @param source [Source, Hash, String, Pathname, ENV] the source input
+    # @param args [Hash] additional arguments for the source
+    # @return [Builder]
     def add_source(source, **args)
       sources << self.class.source(source, **args)
       self
     end
 
-    # Loads config in the following order:
-    #   1. Reads default config
-    #   2. Reads all the config files provided in the order
-    #   3. Reads environment variables
-    def load
-      Config.new(read_from_sources)
+    def load(config_class:)
+      config_class.new(read_from_sources)
     end
 
     def ==(other)

data/lib/config_x/config.rb

@@ -1,44 +1,15 @@
 # frozen_string_literal: true
 
-require "ostruct"
-require "deep_merge/core"
+begin
+  require "dry-struct"
+rescue LoadError
+  raise "The dry-struct gem is required for ConfigX::TypedConfig"
+end
 
 module ConfigX
-  class Config < OpenStruct
-    def initialize(members)
-      super()
-
-      members.each do |key, value|
-        raise ArgumentError, "option keys should be strings" unless key.respond_to?(:to_s)
-
-        key = key.to_s
-
-        if value.is_a?(Hash)
-          value = self.class.new(value)
-        elsif value.is_a?(Array)
-          value = value.map do |element|
-            element.is_a?(Hash) ? self.class.new(element) : element
-          end
-        end
-
-        self[key] = value
-      end
-
-      freeze
-    end
-
-    def with_fallback(fallback)
-      DeepMerge.deep_merge!(
-        to_h,
-        fallback.to_h,
-        overwrite_arrays: true
-      ).then { Config.new(_1) }
-    end
+  class Config < Dry::Struct
+    transform_keys(&:to_sym)
 
-    def to_h
-      each_pair.each_with_object({}) do |(key, value), hash|
-        hash[key] = value.is_a?(Config) ? value.to_h : value
-      end
-    end
+    include Configurable
   end
 end

data/lib/config_x/config_factory.rb

@@ -26,6 +26,10 @@ module ConfigX
       # Default root directory for configuration
       def default_config_root = "config"
 
+      # Default configuration class
+      # @return [Class<ConfigX::Configurable>]
+      def default_config_class = UntypedConfig
+
       # Load method to initialize and load the configuration
       def load(...) = new(...).load
     end
@@ -43,7 +47,8 @@ module ConfigX
       env_separator: self.class.default_env_separator,
       dir_name: self.class.default_dir_name,
       file_name: self.class.default_file_name,
-      config_root: self.class.default_config_root
+      config_root: self.class.default_config_root,
+      config_class: self.class.default_config_class
     )
       @env = env
       @env_prefix = env_prefix
@@ -51,15 +56,16 @@ module ConfigX
       @dir_name = dir_name
       @file_name = file_name
       @config_root = config_root
+      @config_class = config_class
     end
 
     # Loads the configuration from the sources and additional sources.
     # @param additional_sources [Array] additional sources to load configuration from.
-    # @return [Config] the loaded configuration.
+    # @return [UntypedConfig] the loaded configuration.
     def load(*additional_sources)
       (sources + additional_sources)
         .reduce(Builder.new) { |builder, source| builder.add_source(source) }
-        .load
+        .load(config_class:)
     end
 
     private
@@ -87,7 +93,7 @@ module ConfigX
     # @return [Array] the local setting files.
     def local_setting_files
       [
-        (File.join(config_root, "#{file_name}.local.yml") if env != "test"),
+        File.join(config_root, "#{file_name}.local.yml"),
         File.join(config_root, dir_name, "#{env}.local.yml")
       ].compact
     end
@@ -109,5 +115,8 @@ module ConfigX
 
     # The file name for settings.
     attr_reader :file_name
+
+    # The configuration class.
+    attr_reader :config_class
   end
 end

data/lib/config_x/configurable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "deep_merge/core"
+
+module ConfigX
+  module Configurable
+    # @!method to_h
+    #   @abstract
+    #   @return [Hash]
+
+    # Merges the current configuration with a fallback configuration.
+    #
+    # @param fallback [Configurable] the fallback configuration
+    # @return [Configurable] a new Config object with the merged configuration
+    def with_fallback(fallback)
+      DeepMerge.deep_merge!(
+        to_h,
+        fallback.to_h,
+        overwrite_arrays: true
+      ).then { self.class.new(_1) }
+    end
+  end
+end

data/lib/config_x/env_source.rb

@@ -26,7 +26,7 @@ module ConfigX
 
         Array(key.split(separator)[1..])
           .reverse_each
-          .reduce(YAML.load(value)) { |acc, k| {k.downcase => acc} }
+          .reduce(YAML.safe_load(value)) { |acc, k| {k.downcase => acc} }
           .tap { DeepMerge.deep_merge!(_1, config) }
       end
     end

data/lib/config_x/hash_source.rb

@@ -7,11 +7,26 @@ module ConfigX
     attr_reader :source
     protected :source
 
+    class << self
+      def deep_stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] =
+            if Hash === value
+              deep_stringify_keys(value)
+            else
+              value
+            end
+        end
+      end
+    end
+
     def initialize(source)
       @source = source
     end
 
-    def load = source
+    def load
+      self.class.deep_stringify_keys(source)
+    end
 
     def ==(other)
       other.is_a?(self.class) && source == other.source

data/lib/config_x/untyped_config.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module ConfigX
+  # The Config class extends OpenStruct to provide a flexible configuration object.
+  class UntypedConfig < OpenStruct
+    include Configurable
+
+    # @param members [Hash] the initial configuration hash
+    # @raise [ArgumentError] if any of the keys are not convertible to strings
+    def initialize(members)
+      super({})
+
+      members.each do |key, value|
+        raise ArgumentError, "option keys should be strings" unless key.respond_to?(:to_s)
+
+        key = key.to_s
+
+        if value.is_a?(Hash)
+          value = self.class.new(value)
+        elsif value.is_a?(Array)
+          value = value.map do |element|
+            element.is_a?(Hash) ? self.class.new(element) : element
+          end
+        end
+
+        self[key] = value
+      end
+
+      freeze
+    end
+
+    # Converts the Config object to a hash.
+    #
+    # @return [Hash] the configuration as a hash
+    def to_h
+      each_pair.each_with_object({}) do |(key, value), hash|
+        hash[key] = value.is_a?(self.class) ? value.to_h : value
+      end
+    end
+  end
+end

data/lib/config_x/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConfigX
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/config_x.rb

@@ -6,23 +6,26 @@ require_relative "config_x/version"
 module ConfigX
   class << self
     # @api private
+    # @return [Zeitwerk::Loader]
     def loader
       @loader ||= Zeitwerk::Loader.for_gem.tap do |loader|
         loader.ignore("#{__dir__}/configx.rb")
       end
     end
 
+    # @return [Configurable]
     def load(...) = ConfigFactory.load(...)
 
-    def builder = Builder.new
-
     # Loads config from the given source
     # @example
     #   config = ConfigX.from({api: {endpoint: "http://example.com", enabled: true}})
     #   config.api.endpoint # => "http://example.com"
     #   config.api.enabled # => true
-    #
-    def from(source, **args) = builder.add_source(source, **args).load
+    # @return [ConfigX::UntypedConfig]
+    def from(source, **args) = builder.add_source(source, **args).load(config_class: UntypedConfig)
+
+    # @return [ConfigX::Builder]
+    private def builder = Builder.new
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: configx
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Tëma Bolshakov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-06 00:00:00.000000000 Z
+date: 2024-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
@@ -58,22 +58,15 @@ files:
 - lib/config_x/builder.rb
 - lib/config_x/config.rb
 - lib/config_x/config_factory.rb
+- lib/config_x/configurable.rb
 - lib/config_x/env_source.rb
 - lib/config_x/file_source.rb
 - lib/config_x/hash_source.rb
 - lib/config_x/source.rb
+- lib/config_x/untyped_config.rb
 - lib/config_x/version.rb
 - lib/config_x/yaml_source.rb
 - lib/configx.rb
-- sig/config_x.rbs
-- sig/config_x/builder.rbs
-- sig/config_x/config.rbs
-- sig/config_x/config_factory.rbs
-- sig/config_x/env_source.rbs
-- sig/config_x/file_source.rbs
-- sig/config_x/hash_source.rbs
-- sig/config_x/source.rbs
-- sig/config_x/yaml_source.rbs
 homepage: https://github.com/bolshakov/configx
 licenses:
 - MIT
@@ -95,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.10
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Configuration simplified

data/sig/config_x/builder.rbs

@@ -1,21 +0,0 @@
-module ConfigX
-  class Builder
-    type source = Source | Hash[untyped, untyped] | String | Pathname | Object
-
-    def self.load: -> Config
-    def self.source: [T < Source] (source, **untyped) -> T
-
-    def initialize: -> void
-
-    attr_reader sources: Array[Source]
-
-
-    def add_source: (source, **untyped) -> self
-
-    def load: -> Config
-
-    private
-
-    def read_from_sources: -> Hash[untyped, untyped]
-  end
-end

data/sig/config_x/config.rbs

@@ -1,13 +0,0 @@
-module ConfigX
-  class Config
-    def initialize: (Hash[untyped, untyped]) -> void
-
-    def to_h: -> Hash[untyped, untyped]
-
-    def with_fallback: (Config) -> Config
-
-    def each_pair: -> Enumerable[[untyped, untyped]]
-
-    def []=: (untyped, untyped) -> untyped
-  end
-end

data/sig/config_x/config_factory.rbs

@@ -1,55 +0,0 @@
-module ConfigX
-  class ConfigFactory
-    def self.default_config_root: -> String
-
-    def self.default_dir_name: -> String
-
-    def self.default_env_prefix: -> String
-
-    def self.default_env_separator: -> String
-
-    def self.default_env: -> String
-
-    def self.default_file_name: -> String
-
-    def self.load: (
-        ?String env,
-        ?env_prefix: String,
-        ?env_separator: String,
-        ?dir_name: String,
-        ?file_name: String,
-        ?config_root: String
-      ) -> Config
-
-    def initialize: (
-        ?String env,
-        ?env_prefix: String,
-        ?env_separator: String,
-        ?dir_name: String,
-        ?file_name: String,
-        ?config_root: String
-      ) -> void
-
-    def load: -> Config
-
-    private
-
-    def local_setting_files: -> Array[String]
-
-    def setting_files: -> Array[String]
-
-    attr_reader config_root: String
-
-    attr_reader dir_name: String
-
-    attr_reader env_prefix: String
-
-    attr_reader env_separator: String
-
-    attr_reader env: String
-
-    attr_reader file_name: String
-
-    def sources: -> Array[Builder::source]
-  end
-end

data/sig/config_x/env_source.rbs

@@ -1,11 +0,0 @@
-module ConfigX
-  class EnvSource < HashSource
-    type env = Hash[String, String]
-
-    def initialize: (env, prefix: String, separator: String) -> void
-
-    attr_reader env: env
-    attr_reader prefix: String
-    attr_reader separator: String
-  end
-end

data/sig/config_x/file_source.rbs

@@ -1,7 +0,0 @@
-module ConfigX
-  class FileSource < Source
-    def initialize: (String | Pathname) -> void
-
-    attr_reader path: String | Pathname
-  end
-end

data/sig/config_x/hash_source.rbs

@@ -1,8 +0,0 @@
-
-module ConfigX
-  class HashSource < Source
-    def initialize: (Source::config_hash) -> void
-
-    attr_reader source: Source::config_hash
-  end
-end

data/sig/config_x/source.rbs

@@ -1,8 +0,0 @@
-
-module ConfigX
-  class Source
-    type config_hash = Hash[untyped, untyped]
-
-    def load: -> config_hash
-  end
-end

data/sig/config_x/yaml_source.rbs

@@ -1,10 +0,0 @@
-
-module ConfigX
-  class YamlSource < Source
-    def initialize: (String) -> void
-
-    private
-
-    attr_reader source: String
-  end
-end

data/sig/config_x.rbs

@@ -1,18 +0,0 @@
-module ConfigX
-  VERSION: String
-
-  def self.builder: -> Builder
-  def self.from: (Builder::source, **untyped) -> Config
-
-  def self.load: (
-      String env,
-      env_prefix: String,
-      env_separator: String,
-      dir_name: String,
-      file_name: String,
-      config_root: String
-    ) -> Config
-
-
-  def self.loader: -> Zeitwerk::Loader
-end