anyway_config 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae67246988f82692f84ae07b01642fbca38c9f1593b0e4292b335e08654bbf7e
-  data.tar.gz: 045f36927093f3e7929889918dff12d63c61ef58ffcb5fc5793f017dd2da1c5e
+  metadata.gz: 87d32ae676d03c8a9fd3a0b22efe3321d76661f226438f52fd313f4d73b1876d
+  data.tar.gz: 82f2ab5d663b03622f650fbcf8e37216a71d81fdfd9270d54f539fd6253ada9d
 SHA512:
-  metadata.gz: de0f8281daad0d2da4ad557f7099602a46d7fa4476f0a3adfb5b7f14c3abcd44fd020a89fd661a4c9ebeb9b5e70550d37f1b16d01bf68d535ab63877b9ae1661
-  data.tar.gz: 04de1b39c49b4dc39faa12ee199143ca64b3722cbc547e8c41b41bc3e7e365848bae2f06dfc9f99db5693782df4239cd5bbdca99cf2e58e50f38147b2b5dc95e
+  metadata.gz: 9f7952609c7964cc9866fe530a9a519cf981f0551f9979c72f38b2acd31e59edd98d6234f095da99419acd462bcfc7c6b7d5016c41ded3bb0206d7f1e03550b3
+  data.tar.gz: 1559b8e140b7df15164134233fd6c65e11d9283f94c9495a0d92f6afdcc69271cec68a7bc6f5052b8ec06dab35e33f1cadd32f4f044701156bfcc0ca4676ba41

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## master
 
+## 2.2.0 ⛓
+
+- Add RBS signatures and generator. ([@palkan][])
+
+Anyway Config now ships with the basic RBS support. To use config types with Steep, add `library "anyway_config"` to your Steepfile.
+
+We also provide an API to generate a signature for you config class: `MyConfig.to_rbs`. You can use this method to generate a scaffold for your config class.
+
+- Add type coercion support. ([@palkan][])
+
+Example:
+
+```ruby
+class CoolConfig < Anyway::Config
+  attr_config :port, :user
+
+  coerce_types port: :string, user: {dob: :date}
+end
+
+ENV["COOL_USER__DOB"] = "1989-07-01"
+
+config = CoolConfig.new({port: 8080})
+config.port == "8080" #=> true
+config.user["dob"] == Date.new(1989, 7, 1) #=> true
+```
+
+You can also add `.disable_auto_cast!` to your config class to disable automatic conversion.
+
+**Warning** Now values from all sources are coerced (e.g., YAML files). That could lead to a different behaviour.
+
+- Do not dup modules/classes passed as configuration values. ([@palkan][])
+
+- Handle loading empty YAML config files. ([@micahlee][])
+
 ## 2.1.0 (2020-12-29)
 
 - Drop deprecated `attr_config` instance variables support.

data/README.md

@@ -42,12 +42,14 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
   - [Generators](#generators)
 - [Using with Ruby applications](#using-with-ruby)
 - [Environment variables](#environment-variables)
+- [Type coercion](#type-coercion)
 - [Local configuration](#local-files)
 - [Data loaders](#data-loaders)
 - [Source tracing](#tracing)
 - [Pattern matching](#pattern-matching)
 - [Test helpers](#test-helpers)
 - [OptionParser integration](#optionparser-integration)
+- [RBS support](#rbs-support)
 
 ## Main concepts
 
@@ -94,7 +96,7 @@ Or adding to your project:
 
 ```ruby
 # Gemfile
-gem "anyway_config", "~> 2.0.0"
+gem "anyway_config", "~> 2.0"
 ```
 
 ### Supported Ruby versions
@@ -269,6 +271,7 @@ This feature is similar to `Rails.application.config_for` but more powerful:
 | Load data from environment | ❌ | ✅ |
 | Load data from [custom sources](#data-loaders) | ❌ | ✅ |
 | Local config files | ❌ | ✅ |
+| Type coercion | ❌ | ✅ |
 | [Source tracing](#tracing) | ❌ | ✅ |
 | Return Hash with indifferent access | ❌ | ✅ |
 | Support ERB\* within `config/app.yml` | ✅ | ✅ |
@@ -331,7 +334,7 @@ Your config is filled up with values from the following sources (ordered by prio
 
 1) **YAML configuration files**: `RAILS_ROOT/config/my_cool_gem.yml`.
 
-Recognizes Rails environment, supports `ERB`:
+Rails environment is used as the namespace (required); supports `ERB`:
 
 ```yml
 test:
@@ -451,6 +454,22 @@ config.anyway_config.autoload_static_config_path = "path/to/configs"
 **NOTE:** Configs loaded from the `autoload_static_config_path` are **not reloaded in development**. We call them _static_. So, it makes sense to keep only configs necessary for initialization in this folder. Other configs, _dynamic_, could be stored in `app/configs`.
 Or you can store everything in `app/configs` by setting `config.anyway_config.autoload_static_config_path = "app/configs"`.
 
+**NOTE 2**: Since _static_ configs are loaded before initializers, it's not possible to use custom inflection Rules (usually defined in `config/initializers/inflections.rb`) to resolve constant names from files. If you rely on custom inflection rules (see, for example, [#81](https://github.com/palkan/anyway_config/issues/81)), we recommend configuration Rails inflector before initialization as well:
+
+```ruby
+# config/application.rb
+
+# ...
+
+require_relative "initializers/inflections"
+
+module SomeApp
+  class Application < Rails::Application
+    # ...
+  end
+end
+```
+
 ### Generators
 
 Anyway Config provides Rails generators to create new config classes:
@@ -525,13 +544,15 @@ Environmental variables for your config should start with your config name, uppe
 
 For example, if your config name is "mycoolgem", then the env var "MYCOOLGEM_PASSWORD" is used as `config.password`.
 
-Environment variables are automatically type cast:
+By default, environment variables are automatically type cast\*:
 
 - `"True"`, `"t"` and `"yes"` to `true`;
 - `"False"`, `"f"` and `"no"` to `false`;
 - `"nil"` and `"null"` to `nil` (do you really need it?);
 - `"123"` to 123 and `"3.14"` to 3.14.
 
+\* See below for coercion customization.
+
 *Anyway Config* supports nested (_hashed_) env variables—just separate keys with double-underscore.
 
 For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as `config.options["verbose"]`.
@@ -549,6 +570,87 @@ If you want to provide a text-like env variable which contains commas then wrap
 MYCOOLGEM = "Nif-Nif, Naf-Naf and Nouf-Nouf"
 ```
 
+## Type coercion
+
+> 🆕 v2.2.0
+
+You can define custom type coercion rules to convert string data to config values. To do that, use `.coerce_types` method:
+
+```ruby
+class CoolConfig < Anyway::Config
+  config_name :cool
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  coerce_types port: :string, user: {dob: :date}
+end
+
+ENV["COOL_USER__DOB"] = "1989-07-01"
+
+config = CoolConfig.new
+config.port == "8080" # Even though we defined the default value as int, it's converted into a string
+config.user["dob"] == Date.new(1989, 7, 1) #=> true
+```
+
+Type coercion is especially useful to deal with array values:
+
+```ruby
+# To define an array type, provide a hash with two keys:
+#  - type — elements type
+#  - array: true — mark the parameter as array
+coerce_types list: {type: :string, array: true}
+```
+
+It's also could be useful to explicitly define non-array types (to avoid confusion):
+
+```ruby
+coerce_types non_list: :string
+```
+
+Finally, it's possible to disable auto-casting for a particular config completely:
+
+```ruby
+class CoolConfig < Anyway::Config
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  disable_auto_cast!
+end
+
+ENV["COOL_PORT"] = "443"
+
+CoolConfig.new.port == "443" #=> true
+```
+
+**IMPORTANT**: Values provided explicitly (via attribute writers) are not coerced. Coercion is only happening during the load phase.
+
+The following types are supported out-of-the-box: `:string`, `:integer`, `:float`, `:date`, `:datetime`, `:uri`, `:boolean`.
+
+You can use custom deserializers by passing a callable object instead of a type name:
+
+```ruby
+COLOR_TO_HEX = lambda do |raw|
+  case raw
+  when "red"
+    "#ff0000"
+  when "green"
+    "#00ff00"
+  when "blue"
+    "#0000ff"
+  end
+end
+
+class CoolConfig < Anyway::Config
+  attr_config :color
+
+  coerce_types color: COLOR_TO_HEX
+end
+
+CoolConfig.new({color: "red"}).color #=> "#ff0000"
+```
+
 ## Local files
 
 It's useful to have a personal, user-specific configuration in development, which extends the project-wide one.
@@ -610,7 +712,7 @@ In order to support [source tracing](#tracing), you need to wrap the resulting H
 
 ```ruby
 def call(name:, **_opts)
-  trace!(source: :chamber) do
+  trace!(:chamber) do
     Chamber.env.to_h[name] || {}
   end
 end
@@ -790,6 +892,62 @@ describe_options(
 )
 ```
 
+## RBS support
+
+Anyway Config comes with Ruby type signatures (RBS).
+
+To use them with Steep, add `library "anyway_config"` to your Steepfile.
+
+We also provide an API to generate a type signature for your config class:
+
+```ruby
+class MyGem::Config < Anyway::Config
+  attr_config :host, port: 8080, tags: [], debug: false
+
+  coerce_types host: :string, port: :integer,
+    tags: {type: :string, array: true}
+
+  required :host
+end
+```
+
+Then calling `MyGem::Config.to_rbs` will return the following signature:
+
+```rbs
+module MyGem
+  interface _Config
+    def host: () -> String
+    def host=: (String) -> void
+    def port: () -> String?
+    def port=: (String) -> void
+    def tags: () -> Array[String]?
+    def tags=: (Array[String]) -> void
+    def debug: () -> bool
+    def debug?: () -> bool
+    def debug=: (bool) -> void
+  end
+
+  class Config < Anyway::Config
+    include _Config
+  end
+end
+```
+
+### Handling `on_load`
+
+When we use `on_load` callback with a block, we switch the context (via `instance_eval`), and we need to provide type hints for the type checker. Here is an example:
+
+```ruby
+class MyConfig < Anyway::Config
+  on_load do
+    # @type self : MyConfig
+    raise_validation_error("host is invalid") if host.start_with?("localhost")
+  end
+end
+```
+
+Yeah, a lot of annotations 😞 Welcome to the type-safe world!
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/anyway_config](https://github.com/palkan/anyway_config).

data/lib/.rbnext/1995.next/anyway/config.rb

@@ -44,6 +44,7 @@ module Anyway # :nodoc:
       to_h
       to_source_trace
       write_config_attr
+      __type_caster__
     ].freeze
 
     class Error < StandardError; end
@@ -196,6 +197,47 @@ module Anyway # :nodoc:
 
       def new_empty_config() = {}
 
+      def coerce_types(mapping)
+        coercion_mapping.deep_merge!(mapping)
+      end
+
+      def coercion_mapping
+        return @coercion_mapping if instance_variable_defined?(:@coercion_mapping)
+
+        @coercion_mapping = if superclass < Anyway::Config
+          superclass.coercion_mapping.deep_dup
+        else
+          {}
+        end
+      end
+
+      def type_caster(val = nil)
+        return @type_caster unless val.nil?
+
+        @type_caster ||=
+          if coercion_mapping.empty?
+            fallback_type_caster
+          else
+            ::Anyway::TypeCaster.new(coercion_mapping, fallback: fallback_type_caster)
+          end
+      end
+
+      def fallback_type_caster(val = nil)
+        return (@fallback_type_caster = val) unless val.nil?
+
+        return @fallback_type_caster if instance_variable_defined?(:@fallback_type_caster)
+
+        @fallback_type_caster = if superclass < Anyway::Config
+          superclass.fallback_type_caster.deep_dup
+        else
+          ::Anyway::AutoCast
+        end
+      end
+
+      def disable_auto_cast!
+        @fallback_type_caster = ::Anyway::NoCast
+      end
+
       private
 
       def define_config_accessor(*names)
@@ -373,7 +415,7 @@ module Anyway # :nodoc:
         values[name].nil? || (values[name].is_a?(String) && values[name].empty?)
       end.then do |missing|
         next if missing.empty?
-        raise_validation_error "The following config parameters are missing or empty: #{missing.join(", ")}"
+        raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"
       end
     end
 
@@ -381,11 +423,16 @@ module Anyway # :nodoc:
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)
 
+      val = __type_caster__.coerce(key, val)
       public_send(:"#{key}=", val)
     end
 
     def raise_validation_error(msg)
       raise ValidationError, msg
     end
+
+    def __type_caster__
+      self.class.type_caster
+    end
   end
 end

data/lib/.rbnext/1995.next/anyway/dynamic_config.rb

@@ -12,11 +12,15 @@ module Anyway
       #   my_config = Anyway::Config.for(:my_app)
       #   # will load data from config/my_app.yml, secrets.my_app, ENV["MY_APP_*"]
       #
-      def for(name, **options)
+      def for(name, auto_cast: true, **options)
         config = allocate
         options[:env_prefix] ||= name.to_s.upcase
         options[:config_path] ||= config.resolve_config_path(name, options[:env_prefix])
-        config.load_from_sources(new_empty_config, name: name, **options)
+
+        raw_config = config.load_from_sources(new_empty_config, name: name, **options)
+        return raw_config unless auto_cast
+
+        AutoCast.call(raw_config)
       end
     end
 

data/lib/.rbnext/1995.next/anyway/tracing.rb

@@ -34,11 +34,11 @@ module Anyway
 
       def record_value(val, *path, **opts)
         key = path.pop
-        if val.is_a?(Hash)
+        trace = if val.is_a?(Hash)
           Trace.new.tap { _1.merge_values(val, **opts) }
         else
           Trace.new(:value, val, **opts)
-        end => trace
+        end
 
         target_trace = path.empty? ? self : value.dig(*path)
         target_trace.value[key.to_s] = trace

data/lib/.rbnext/2.7/anyway/auto_cast.rb

@@ -7,27 +7,47 @@ module Anyway
     # and doesn't start/end with quote
     ARRAY_RXP = /\A[^'"].*\s*,\s*.*[^'"]\z/
 
-    def self.call(val)
-      return val unless String === val
+    class << self
+      def call(val)
+        return val unless val.is_a?(::Hash) || val.is_a?(::String)
 
-      case val
-      when ARRAY_RXP
-        val.split(/\s*,\s*/).map { |_1| call(_1) }
-      when /\A(true|t|yes|y)\z/i
-        true
-      when /\A(false|f|no|n)\z/i
-        false
-      when /\A(nil|null)\z/i
-        nil
-      when /\A\d+\z/
-        val.to_i
-      when /\A\d*\.\d+\z/
-        val.to_f
-      when /\A['"].*['"]\z/
-        val.gsub(/(\A['"]|['"]\z)/, "")
-      else
-        val
+        case val
+        when Hash
+          val.transform_values { |_1| call(_1) }
+        when ARRAY_RXP
+          val.split(/\s*,\s*/).map { |_1| call(_1) }
+        when /\A(true|t|yes|y)\z/i
+          true
+        when /\A(false|f|no|n)\z/i
+          false
+        when /\A(nil|null)\z/i
+          nil
+        when /\A\d+\z/
+          val.to_i
+        when /\A\d*\.\d+\z/
+          val.to_f
+        when /\A['"].*['"]\z/
+          val.gsub(/(\A['"]|['"]\z)/, "")
+        else
+          val
+        end
+      end
+
+      def cast_hash(obj)
+        obj.transform_values do |val|
+          val.is_a?(::Hash) ? cast_hash(val) : call(val)
+        end
+      end
+
+      def coerce(_key, val)
+        call(val)
       end
     end
   end
+
+  module NoCast
+    def self.call(val) ;  val; end
+
+    def self.coerce(_key, val) ;  val; end
+  end
 end

data/lib/.rbnext/2.7/anyway/config.rb

@@ -44,6 +44,7 @@ module Anyway # :nodoc:
       to_h
       to_source_trace
       write_config_attr
+      __type_caster__
     ].freeze
 
     class Error < StandardError; end
@@ -196,6 +197,47 @@ module Anyway # :nodoc:
 
       def new_empty_config() ;  {}; end
 
+      def coerce_types(mapping)
+        coercion_mapping.deep_merge!(mapping)
+      end
+
+      def coercion_mapping
+        return @coercion_mapping if instance_variable_defined?(:@coercion_mapping)
+
+        @coercion_mapping = if superclass < Anyway::Config
+          superclass.coercion_mapping.deep_dup
+        else
+          {}
+        end
+      end
+
+      def type_caster(val = nil)
+        return @type_caster unless val.nil?
+
+        @type_caster ||=
+          if coercion_mapping.empty?
+            fallback_type_caster
+          else
+            ::Anyway::TypeCaster.new(coercion_mapping, fallback: fallback_type_caster)
+          end
+      end
+
+      def fallback_type_caster(val = nil)
+        return (@fallback_type_caster = val) unless val.nil?
+
+        return @fallback_type_caster if instance_variable_defined?(:@fallback_type_caster)
+
+        @fallback_type_caster = if superclass < Anyway::Config
+          superclass.fallback_type_caster.deep_dup
+        else
+          ::Anyway::AutoCast
+        end
+      end
+
+      def disable_auto_cast!
+        @fallback_type_caster = ::Anyway::NoCast
+      end
+
       private
 
       def define_config_accessor(*names)
@@ -373,7 +415,7 @@ module Anyway # :nodoc:
         values[name].nil? || (values[name].is_a?(String) && values[name].empty?)
       end.then do |missing|
         next if missing.empty?
-        raise_validation_error "The following config parameters are missing or empty: #{missing.join(", ")}"
+        raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"
       end
     end
 
@@ -381,11 +423,16 @@ module Anyway # :nodoc:
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)
 
+      val = __type_caster__.coerce(key, val)
       public_send(:"#{key}=", val)
     end
 
     def raise_validation_error(msg)
       raise ValidationError, msg
     end
+
+    def __type_caster__
+      self.class.type_caster
+    end
   end
 end

data/lib/.rbnext/2.7/anyway/rbs.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+using RubyNext;
+module Anyway
+  module RBSGenerator
+    TYPE_TO_CLASS = {
+      string: "String",
+      integer: "Integer",
+      float: "Float",
+      date: "Date",
+      datetime: "DateTime",
+      uri: "URI",
+      boolean: "bool"
+    }.freeze
+
+    # Generate RBS signature from a config class
+    def to_rbs
+      *namespace, class_name = name.split("::")
+
+      buf = []
+      indent = 0
+      interface_name = "_Config"
+
+      if namespace.empty?
+        interface_name = "_#{class_name}"
+      else
+        buf << "module #{namespace.join("::")}"
+        indent += 1
+      end
+
+      # Using interface emulates a module we include to provide getters and setters
+      # (thus making `super` possible)
+      buf << "#{"  " * indent}interface #{interface_name}"
+      indent += 1
+
+      # Generating setters and getters for config attributes
+      config_attributes.each do |param|
+        type = coercion_mapping[param] || defaults[param.to_s]
+
+        type =
+          case; when ((__m__ = type)) && false 
+          when (NilClass === __m__)
+            "untyped"
+          when (Symbol === __m__)
+            TYPE_TO_CLASS.fetch(type) { defaults[param] ? "Symbol" : "untyped" }
+          when (Array === __m__)
+            "Array[untyped]"
+          when ((__m__.respond_to?(:deconstruct_keys) && (((__m_hash__src__ = __m__.deconstruct_keys(nil)) || true) && (Hash === __m_hash__src__ || Kernel.raise(TypeError, "#deconstruct_keys must return Hash"))) && (__m_hash__ = __m_hash__src__.dup)) && ((__m_hash__.key?(:array) && __m_hash__.key?(:type)) && (((array = __m_hash__.delete(:array)) || true) && (((type = __m_hash__.delete(:type)) || true) && __m_hash__.empty?))))
+            "Array[#{TYPE_TO_CLASS.fetch(type, "untyped")}]"
+          when (Hash === __m__)
+            "Hash[string,untyped]"
+          when ((TrueClass === __m__) || (FalseClass === __m__))
+            "bool"
+          else
+            type.class.to_s
+          end
+
+        getter_type = type
+        getter_type = "#{type}?" unless required_attributes.include?(param)
+
+        buf << "#{"  " * indent}def #{param}: () -> #{getter_type}"
+        buf << "#{"  " * indent}def #{param}=: (#{type}) -> void"
+
+        if type == "bool" || type == "bool?"
+          buf << "#{"  " * indent}def #{param}?: () -> #{getter_type}"
+        end
+      end
+
+      indent -= 1
+      buf << "#{"  " * indent}end"
+
+      buf << ""
+
+      buf << "#{"  " * indent}class #{class_name} < #{superclass.name}"
+      indent += 1
+
+      buf << "#{"  " * indent}include #{interface_name}"
+
+      indent -= 1
+      buf << "#{"  " * indent}end"
+
+      unless namespace.empty?
+        buf << "end"
+      end
+
+      buf << ""
+
+      buf.join("\n")
+    end
+  end
+
+  Config.extend RBSGenerator
+end

data/lib/.rbnext/2.7/anyway/tracing.rb

@@ -34,13 +34,11 @@ module Anyway
 
       def record_value(val, *path, **opts)
         key = path.pop
-        (__m__ = if val.is_a?(Hash)
-  Trace.new.tap { |_1|
-    _1.merge_values(val, **opts)
-  }
-else
-  Trace.new(:value, val, **opts)
-end) && (((trace = __m__) || true) || Kernel.raise(NoMatchingPatternError, __m__.inspect))
+        trace = if val.is_a?(Hash)
+          Trace.new.tap { |_1| _1.merge_values(val, **opts) }
+        else
+          Trace.new(:value, val, **opts)
+        end
 
         target_trace = path.empty? ? self : value.dig(*path)
         target_trace.value[key.to_s] = trace