typed_env 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c7ae6a6af04309a81f2e6eaf57c993e9be108724607186b38582473c6a5eaee
+  data.tar.gz: ce9e3a68c4989bd1cc30a7dd3e120c7e13b6f07d4b4851f1574802c3add8b8e7
+SHA512:
+  metadata.gz: c8e5554af8efebd63f4170c90d4d4d45e9e468ed6cd9d75afd804ed9483635802ddbb3f83566821483d9dad0131e85914fcb6e1ed004dc63ac90ecee649d3396
+  data.tar.gz: a9f03120ccacd3821349baf59d947aa811dc03cd872ff3289c6e2df3a5cdf28186c17abc88eb95102de79fe839c8417a72e6a93bb65ec3e9273f53b77fb867c2

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this gem are recorded here. The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-11-07
+
+First release on rubygems.org. Until now the gem was installed from GitHub as `env_settings`, module `EnvSettings`
+(the name is another gem's on rubygems.org): it is `typed_env`, module `TypedEnv`, from this version on —
+`EnvSettings::Base` becomes `TypedEnv::Base`, `EnvSettings::ValidationError` `TypedEnv::ValidationError`.
+
+### Added
+
+- The `var` DSL: typed environment variables (`string`, `integer`, `float`, `boolean`, `array`, `hash`, `symbol`) with
+  defaults, `name?` for booleans, `name_present?`, `all` / `to_h`.
+- Validations: presence, length, format and inclusion built in; every ActiveModel validation when ActiveModel is loaded.
+  `validate!` checks every var; a value written is validated before it is written.
+- Reader and writer callbacks, per var and default for the class: settings kept elsewhere than `ENV`. Read-only
+  without a writer.
+
+### Fixed
+
+- `validate!` with ActiveModel ran every var's rules N + 1 times (a full validation, then each var again, each time
+  all rules); now once.
+- A rule could not read a var declared after it without rules of its own (`if: -> { other }` raised `NameError`).
+- The validator kept a value in an instance variable per setting, which gave its class a shape per setting: Ruby 3.4
+  warned "reached 8 shape variations" at boot for more than eight validated vars.
+- README: writer examples used the `key` parameter callbacks no longer receive.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Ekzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,759 @@
+# TypedEnv
+
+Type-safe environment variables management for Ruby applications with a clean DSL inspired by rails-settings-cached.
+
+## Features
+
+- Type-safe environment variable access
+- Support for multiple types: string, integer, float, boolean, array, hash, symbol
+- Built-in validations (presence, length, format, inclusion)
+- Clean, Rails-like DSL
+- Default values
+- Boolean helper methods
+- Custom reader/writer callbacks for flexible storage (database, Redis, files, etc.)
+- Read-only by default for security
+- ActiveModel validations support (optional)
+- Fully tested
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'typed_env'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install typed_env
+```
+
+## Usage
+
+### Basic Setup
+
+Create a class that inherits from `TypedEnv::Base` and define your environment variables:
+
+```ruby
+
+class Env < TypedEnv::Base
+  var :app_name, type: :string, default: "MyApp"
+  var :port, type: :integer, default: 3000
+  var :debug, type: :boolean, default: false
+  var :database_url, type: :string, validates: { presence: true }
+  var :allowed_hosts, type: :array, default: []
+  var :redis_config, type: :hash, default: {}
+end
+```
+
+By default, all variables are **read-only** and read from `ENV`. To enable writing or custom storage, see [Custom Reader/Writer Callbacks](#custom-readerwriter-callbacks).
+
+### Reading Values
+
+```ruby
+# Simple access
+Env.app_name          # => "MyApp"
+Env.port              # => 3000
+
+# Boolean helper
+Env.debug?            # => false
+
+# Presence check
+Env.database_url_present?  # => true/false
+
+# Get all settings as hash
+Env.all               # => { app_name: "MyApp", port: 3000, ... }
+Env.to_h              # Same as .all
+```
+
+### Setting Values
+
+**Important:** By default, all variables are read-only. To enable writing, you must provide a `writer` callback.
+
+```ruby
+# This will raise ReadOnlyError
+Env.app_name = "NewApp" # Raises TypedEnv::ReadOnlyError
+
+# To make a variable writable, provide a writer callback
+class Env < TypedEnv::Base
+  var :app_name,
+      type: :string,
+      default: "MyApp",
+      writer: ->(value, setting) { ENV[setting[:env_key]] = value.to_s }
+end
+
+Env.app_name = "NewApp" # Works
+```
+
+### Supported Types
+
+#### String (default)
+
+```ruby
+var :app_name, type: :string, default: "MyApp"
+# ENV["APP_NAME"] = "MyApp" => "MyApp"
+```
+
+#### Integer
+
+```ruby
+var :port, type: :integer, default: 3000
+# ENV["PORT"] = "5000" => 5000
+```
+
+#### Float
+
+```ruby
+var :price, type: :float, default: 9.99
+# ENV["PRICE"] = "19.99" => 19.99
+```
+
+#### Boolean
+
+```ruby
+var :debug, type: :boolean, default: false
+# ENV["DEBUG"] = "true"  => true
+# ENV["DEBUG"] = "1"     => true
+# ENV["DEBUG"] = "yes"   => true
+# ENV["DEBUG"] = "on"    => true
+# ENV["DEBUG"] = "false" => false
+# ENV["DEBUG"] = "0"     => false
+
+# Boolean helper method
+Env.debug? # => true/false
+```
+
+#### Array
+
+```ruby
+var :allowed_hosts, type: :array, default: []
+
+# JSON format
+# ENV["ALLOWED_HOSTS"] = '["host1", "host2"]' => ["host1", "host2"]
+
+# Comma-separated format
+# ENV["ALLOWED_HOSTS"] = "host1, host2, host3" => ["host1", "host2", "host3"]
+```
+
+#### Hash
+
+```ruby
+var :redis_config, type: :hash, default: {}
+
+# JSON format
+# ENV["REDIS_CONFIG"] = '{"host": "localhost", "port": 6379}'
+# => { "host" => "localhost", "port" => 6379 }
+```
+
+#### Symbol
+
+```ruby
+var :log_level, type: :symbol, default: :info
+# ENV["LOG_LEVEL"] = "debug" => :debug
+```
+
+### Validations
+
+#### Presence
+
+```ruby
+var :database_url, validates: { presence: true }
+```
+
+#### Length
+
+```ruby
+var :username, validates: {
+  length: {
+    minimum: 3,
+    maximum: 20
+  }
+}
+
+# Or with range
+var :username, validates: {
+  length: { in: 3..20 }
+}
+```
+
+#### Format (Regex)
+
+```ruby
+var :email, validates: {
+  format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i }
+}
+
+# With custom message
+var :email, validates: {
+  format: {
+    with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
+    message: "must be a valid email address"
+  }
+}
+```
+
+#### Inclusion
+
+```ruby
+var :environment, validates: {
+  inclusion: { in: %w[development test production] }
+}
+```
+
+#### Multiple Validations
+
+```ruby
+var :api_key, validates: {
+  presence: true,
+  length: { minimum: 32 },
+  format: { with: /\A[a-zA-Z0-9]+\z/ }
+}
+```
+
+### Running Validations
+
+```ruby
+# Validate all settings at once
+Env.validate!
+
+# Will raise TypedEnv::ValidationError if any validation fails
+```
+
+It's recommended to run validations during application initialization:
+
+```ruby
+# config/initializers/typed_env.rb (Rails)
+Env.validate!
+```
+
+### Automatic Validation on Write
+
+When you assign a value to a variable with validations, it's automatically validated **before** writing to storage:
+
+```ruby
+class Env < TypedEnv::Base
+  default_writer ->(value, setting) { Setting.find_or_create_by(key: setting[:env_key]).update!(value: value) }
+
+  var :username,
+      type: :string,
+      validates: { presence: true, length: { minimum: 3, maximum: 20 } }
+
+  var :email,
+      type: :string,
+      validates: { format: { with: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i } }
+end
+
+# These will raise ValidationError BEFORE writing to database
+Env.username = ""           # Raises: "Username can't be blank"
+Env.username = "ab"         # Raises: "Username is too short (minimum is 3 characters)"
+Env.email = "invalid"       # Raises: "Email is invalid"
+
+# Only valid values are written to storage
+Env.username = "john"       # Works - writes to database
+Env.email = "j@example.com" # Works - writes to database
+```
+
+This prevents invalid data from being stored and ensures data integrity at the assignment level.
+
+## ActiveModel Validations (Optional)
+
+TypedEnv automatically uses ActiveModel validations if `activemodel` gem is available. This provides:
+
+- More validation options (numericality, comparison, exclusion, etc.)
+- Better error messages with I18n support
+- Custom validators
+- Full compatibility with Rails
+
+### Installation with ActiveModel
+
+```ruby
+# Gemfile
+gem 'typed_env'
+gem 'activemodel'  # Optional, but recommended for Rails projects
+```
+
+### ActiveModel Validation Examples
+
+```ruby
+class Env < TypedEnv::Base
+  # Numericality validation
+  var :port,
+      type: :integer,
+      default: 3000,
+      validates: {
+        numericality: {
+          only_integer: true,
+          greater_than: 0,
+          less_than: 65536
+        }
+      }
+
+  var :timeout,
+      type: :float,
+      validates: {
+        numericality: { greater_than_or_equal_to: 0 }
+      }
+
+  # Comparison validation
+  var :min_value, type: :integer, default: 0
+  var :max_value,
+      type: :integer,
+      default: 100,
+      validates: {
+        comparison: { greater_than: :min_value }
+      }
+
+  # Exclusion validation
+  var :username,
+      validates: {
+        exclusion: { in: %w[admin root superuser] }
+      }
+
+  # Absence validation (for deprecated variables)
+  var :legacy_option,
+      validates: { absence: true }
+
+  # Custom validators
+  var :api_endpoint,
+      validates: { url: true }  # Uses custom UrlValidator
+end
+```
+
+### Validation Syntax
+
+TypedEnv uses **ActiveModel-compatible validation syntax**. This means:
+
+- **With ActiveModel** (`activemodel` gem installed): Full ActiveModel validations with rich features
+- **Without ActiveModel**: Built-in simple validations with the same syntax but limited to: `presence`, `length`, `format`, `inclusion`
+
+The syntax is identical in both cases, so your code works seamlessly:
+
+```ruby
+# This syntax works with AND without activemodel
+var :email, validates: {
+  presence: true,
+  format: { with: /regex/, message: "is not valid" }
+}
+
+# ActiveModel-only validators (requires activemodel gem)
+var :age, validates: {
+  numericality: { greater_than: 0, less_than: 150 }  # Only with ActiveModel
+}
+
+var :password, validates: {
+  confirmation: true  # Only with ActiveModel
+}
+```
+
+**Recommendation**: Install `activemodel` gem for Rails projects to get full validation features.
+
+### Rails Integration
+
+Create an initializer:
+
+```ruby
+# config/initializers/var.rb
+class Env < TypedEnv::Base
+  var :app_name, type: :string, default: "MyRailsApp"
+  var :port, type: :integer, default: 3000
+  var :database_url, type: :string, validates: { presence: true }
+  var :redis_url, type: :string, default: "redis://localhost:6379/0"
+  var :smtp_host, type: :string
+  var :smtp_port, type: :integer, default: 587
+  var :enable_cache, type: :boolean, default: false
+  var :allowed_hosts, type: :array, default: []
+  var :environment, type: :string, validates: {
+    inclusion: %w[development test staging production]
+  }
+end
+
+# Validate on startup
+Env.validate!
+```
+
+Then use throughout your application:
+
+```ruby
+# config/database.yml
+default: &default
+  url: <%= Env.database_url %>
+
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: Env.redis_url }
+
+# Anywhere in your code
+if Env.enable_cache?
+  # Do something
+end
+```
+
+## Custom Reader/Writer Callbacks
+
+TypedEnv allows you to define custom callbacks for reading and writing variables, enabling flexible storage backends like databases, Redis, or files.
+
+### Individual Variable Callbacks
+
+```ruby
+
+class Env < TypedEnv::Base
+  # Read-only from ENV (default behavior)
+  var :database_url, type: :string, validates: { presence: true }
+
+  # Custom reader from database
+  var :maintenance_mode,
+      type: :boolean,
+      default: false,
+      reader: ->(setting) { Setting.find_by(key: setting[:env_key])&.value }
+
+  # Custom reader and writer
+  var :feature_flags,
+      type: :hash,
+      default: {},
+      reader: ->(setting) {
+        value = Redis.current.get("settings:#{setting[:env_key]}")
+        value ? JSON.parse(value) : nil
+      },
+      writer: ->(value, setting) {
+        Redis.current.set("settings:#{setting[:env_key]}", value.to_json)
+      }
+end
+
+# Usage
+Env.maintenance_mode # Reads from database
+Env.feature_flags = { x: true } # Writes to Redis
+Env.database_url = "new" # Raises ReadOnlyError (no writer)
+```
+
+### Global Default Callbacks
+
+Set default reader/writer for all variables:
+
+```ruby
+
+class Env < TypedEnv::Base
+  # All variables will use these callbacks by default
+  default_reader ->(setting) {
+    Setting.find_by(key: setting[:env_key])&.value || ENV[setting[:env_key]]
+  }
+
+  default_writer ->(value, setting) {
+    Setting.find_or_create_by(key: setting[:env_key]).update!(value: value)
+  }
+
+  # Now all variables are readable/writable through database
+  var :api_key, type: :string, default: "default_key"
+  var :timeout, type: :integer, default: 30
+
+  # Can override for specific variables
+  var :secret_key,
+      type: :string,
+      reader: ->(setting) { ENV[setting[:env_key]] }, # Only from ENV
+      writer: nil # Explicitly read-only
+end
+
+# Block syntax is also supported
+class Env < TypedEnv::Base
+  default_reader do |setting|
+    Setting.find_by(key: setting[:env_key])&.value || ENV[setting[:env_key]]
+  end
+
+  default_writer do |value, setting|
+    Setting.find_or_create_by(key: setting[:env_key]).update!(value: value)
+  end
+end
+```
+
+### Callback Parameters
+
+Callbacks receive the following parameters:
+
+- `value` (writer only) - The value being written, already validated
+- `setting` - Full configuration hash with: `:type`, `:default`, `:validates`, `:env_key` (the uppercase ENV key,
+  e.g. "API_KEY"), etc.
+
+**Reader callback:**
+```ruby
+reader: ->(setting) {
+  # Must return raw value (string/nil)
+  # Type coercion is applied automatically
+}
+```
+
+**Writer callback:**
+```ruby
+writer: ->(value, setting) {
+  # Receives the value to write
+  # No return value expected
+}
+```
+
+### Practical Examples
+
+#### ActiveRecord Storage
+
+```ruby
+
+class Env < TypedEnv::Base
+  default_reader ->(setting) {
+    Setting.find_by(key: setting[:env_key])&.value || ENV[setting[:env_key]]
+  }
+
+  default_writer ->(value, setting) {
+    Setting.find_or_create_by(key: setting[:env_key]).update!(value: value)
+  }
+
+  var :maintenance_mode, type: :boolean, default: false
+  var :max_connections, type: :integer, default: 10
+end
+```
+
+#### Redis Storage
+
+```ruby
+
+class Env < TypedEnv::Base
+  default_reader ->(setting) {
+    Redis.current.get("app:settings:#{setting[:env_key]}")
+  }
+
+  default_writer ->(value, setting) {
+    Redis.current.set("app:settings:#{setting[:env_key]}", value.to_s)
+  }
+
+  var :rate_limit, type: :integer, default: 100
+  var :feature_x_enabled, type: :boolean, default: false
+end
+```
+
+#### YAML File Storage
+
+```ruby
+
+class Env < TypedEnv::Base
+  SETTINGS_FILE = "config/runtime_settings.yml"
+
+  default_reader ->(setting) {
+    return ENV[setting[:env_key]] unless File.exist?(SETTINGS_FILE)
+    YAML.load_file(SETTINGS_FILE)[setting[:env_key]]
+  }
+
+  default_writer ->(value, setting) {
+    data = File.exist?(SETTINGS_FILE) ? YAML.load_file(SETTINGS_FILE) : {}
+    data[setting[:env_key]] = value.to_s
+    File.write(SETTINGS_FILE, data.to_yaml)
+  }
+
+  var :log_level, type: :symbol, default: :info
+end
+```
+
+#### Vault/Secrets Manager
+
+```ruby
+
+class Env < TypedEnv::Base
+  var :api_key,
+      type: :string,
+      reader: ->(setting) {
+        Vault.logical.read("secret/data/#{setting[:env_key]}")&.data&.dig(:data, :value)
+      },
+      writer: ->(value, setting) {
+        Vault.logical.write("secret/data/#{setting[:env_key]}", data: { value: value })
+      }
+end
+```
+
+#### Mixed Strategy
+
+```ruby
+
+class Env < TypedEnv::Base
+  # Default: read from ENV (no writer = read-only)
+  var :database_url, type: :string, validates: { presence: true }
+
+  # Runtime settings in database
+  var :maintenance_mode,
+      type: :boolean,
+      default: false,
+      reader: ->(setting) { Setting.get(setting[:env_key]) },
+      writer: ->(value, setting) { Setting.set(setting[:env_key], value) }
+
+  # Feature flags in Redis
+  var :feature_flags,
+      type: :hash,
+      default: {},
+      reader: ->(setting) { JSON.parse(Redis.current.get(setting[:env_key]) || "{}") },
+      writer: ->(value, setting) { Redis.current.set(setting[:env_key], value.to_json) }
+
+  # Secrets in Vault
+  var :stripe_secret_key,
+      type: :string,
+      reader: ->(setting) { Vault.read("secret/#{setting[:env_key]}") }
+  # No writer = read-only
+end
+```
+
+### Additional Use Cases
+
+#### Runtime Configuration with Database
+
+Settings that can be changed through admin panel without restart:
+
+```ruby
+# ActiveRecord model
+class Setting < ApplicationRecord
+  # Table: settings (key:string, value:text)
+
+  def self.get(key)
+    find_by(key: key)&.value
+  end
+
+  def self.set(key, value)
+    find_or_create_by(key: key).update!(value: value.to_s)
+  end
+end
+
+# TypedEnv configuration
+class Env < TypedEnv::Base
+  default_reader ->(setting) { Setting.get(setting[:env_key]) || ENV[setting[:env_key]] }
+  default_writer ->(value, setting) { Setting.set(setting[:env_key], value) }
+
+  var :maintenance_mode, type: :boolean, default: false
+  var :max_upload_size, type: :integer, default: 10_485_760
+  var :feature_x_enabled, type: :boolean, default: false
+end
+
+# Usage in admin controller
+class AdminController < ApplicationController
+  def toggle_maintenance
+    Env.maintenance_mode = params[:enabled]
+    redirect_to admin_path, notice: "Maintenance mode updated"
+  end
+end
+```
+
+#### Feature Flags with Redis
+
+Fast feature flags with minimal latency:
+
+```ruby
+class Env < TypedEnv::Base
+  var :feature_flags,
+      type: :hash,
+      default: {},
+      reader: ->(setting) {
+        value = Redis.current.get("flags:#{setting[:env_key]}")
+        value ? JSON.parse(value) : nil
+      },
+      writer: ->(value, setting) {
+        Redis.current.set("flags:#{setting[:env_key]}", value.to_json)
+      }
+end
+
+# Usage
+Env.feature_flags = {
+  new_ui: true,
+  beta_feature: false
+}
+
+if Env.feature_flags[:new_ui]
+  render :new_design
+else
+  render :old_design
+end
+```
+
+#### Caching Expensive Operations
+
+```ruby
+class Env < TypedEnv::Base
+  @vault_cache = {}
+
+  var :secret_key,
+      reader: ->(setting) {
+        @vault_cache[setting[:env_key]] ||= begin
+          secret = Vault.logical.read("secret/#{setting[:env_key]}")
+          secret&.data&.dig(:data, :value)
+        end
+      }
+end
+```
+
+#### Logging Changes
+
+```ruby
+class Env < TypedEnv::Base
+  default_writer ->(value, setting) {
+    old_value = Setting.get(setting[:env_key])
+    Setting.set(setting[:env_key], value)
+
+    Rails.logger.info(
+      "Setting changed: #{setting[:env_key]} = #{value.inspect} (was: #{old_value.inspect})"
+    )
+  }
+end
+```
+
+### Error Handling
+
+```ruby
+# ReadOnlyError is raised when trying to write without a writer
+begin
+  Env.database_url = "new_url"
+rescue TypedEnv::ReadOnlyError => e
+  puts e.message
+  # => "Cannot write to 'database_url': variable is read-only. Provide a writer callback to enable writing."
+end
+```
+
+## Example: Replacing ENV.fetch
+
+**Before:**
+```ruby
+DATABASE_URL = ENV.fetch('DATABASE_URL')
+PORT = ENV.fetch('PORT', 3000).to_i
+DEBUG = ENV.fetch('DEBUG', 'false') == 'true'
+ALLOWED_HOSTS = ENV.fetch('ALLOWED_HOSTS', '').split(',').map(&:strip)
+```
+
+**After:**
+
+```ruby
+
+class Env < TypedEnv::Base
+  var :database_url, validates: { presence: true }
+  var :port, type: :integer, default: 3000
+  var :debug, type: :boolean, default: false
+  var :allowed_hosts, type: :array, default: []
+end
+
+Env.database_url
+Env.port
+Env.debug?
+Env.allowed_hosts
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ekzo-dev/typed_env.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/typed_env/base.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+begin
+  require "active_model"
+rescue LoadError
+  # ActiveModel is optional
+end
+
+module TypedEnv
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class ReadOnlyError < Error; end
+
+  class Base
+    class << self
+      def var(name, type: :string, default: nil, validates: nil, reader: nil, writer: nil)
+        env_key = name.to_s.upcase
+
+        settings[name] = {
+          type: type,
+          default: default,
+          validates: validates,
+          env_key: env_key,
+          reader: reader,
+          writer: writer
+        }
+
+        # Register ActiveModel validations if available. Every var gets an accessor on the validator once it exists, so a
+        # rule of one may read another (`if: -> { other }`) whichever was declared first.
+        if defined?(ActiveModel::Validations)
+          ensure_validator_class! if validates
+          validator_class&.add_attribute(name, self)
+          validator_class.validates name, **validates if validates.is_a?(Hash)
+        end
+
+        define_singleton_method(name) do
+          get_value(name)
+        end
+
+        define_singleton_method("#{name}=") do |value|
+          set_value(name, value)
+        end
+
+        # Define boolean helper method for boolean types
+        if type == :boolean
+          define_singleton_method("#{name}?") do
+            !!get_value(name)
+          end
+        end
+
+        # Define presence check
+        define_singleton_method("#{name}_present?") do
+          value = get_value(name)
+          !value.nil? && value != ""
+        end
+      end
+
+      def settings
+        @settings ||= {}
+      end
+
+      def validator_class
+        @validator_class
+      end
+
+      def ensure_validator_class!
+        return if @validator_class
+
+        parent_class = self
+        @validator_class = Class.new do
+          include ActiveModel::Validations if defined?(ActiveModel::Validations)
+          include ActiveModel::Model if defined?(ActiveModel::Model)
+
+          # Values being validated, kept in one hash rather than an instance variable per setting: an instance
+          # gets one value (validate_var!) and every setting a validator of its own, so per-setting variables
+          # gave the class a shape per setting, which Ruby warns of from the eighth on.
+          def initialize(*)
+            @values = {}
+            super
+          end
+
+          # Method to add new vars
+          def self.add_attribute(name, parent_class)
+            # Check if value is set on instance, otherwise read from parent
+            define_method(name) do
+              @values.key?(name) ? @values[name] : parent_class.get_value(name)
+            end
+
+            define_method("#{name}=") do |value|
+              @values[name] = value
+            end
+          end
+
+          # Accessors for the settings defined so far; later ones come through add_attribute
+          parent_class.settings.keys.each do |key|
+            add_attribute(key, parent_class)
+          end
+
+          # For ActiveModel error messages
+          def self.model_name
+            ActiveModel::Name.new(self, nil, "TypedEnv")
+          end
+        end
+      end
+
+      def default_reader(callable = nil, &block)
+        @default_reader = callable || block
+      end
+
+      def default_writer(callable = nil, &block)
+        @default_writer = callable || block
+      end
+
+      def get_default_reader
+        @default_reader
+      end
+
+      def get_default_writer
+        @default_writer
+      end
+
+      def get_value(name)
+        setting = settings[name]
+        return nil unless setting
+
+        # Use custom reader if provided
+        if setting[:reader]
+          raw_value = setting[:reader].call(setting)
+        elsif get_default_reader
+          raw_value = get_default_reader.call(setting)
+        else
+          # Default behavior: read from ENV
+          raw_value = ENV[setting[:env_key]]
+        end
+
+        if raw_value.nil?
+          return setting[:default]
+        end
+
+        coerce_value(raw_value, setting[:type])
+      end
+
+      def set_value(name, value)
+        setting = settings[name]
+        return unless setting
+
+        # Validate before writing if validations are defined
+        validate_var!(name, value) if setting[:validates]
+
+        # Use custom writer if provided
+        if setting[:writer]
+          setting[:writer].call(value, setting)
+        elsif get_default_writer
+          get_default_writer.call(value, setting)
+        else
+          # Default behavior: raise error (read-only)
+          raise ReadOnlyError, "Cannot write to '#{name}': variable is read-only. Provide a writer callback to enable writing."
+        end
+      end
+
+      def coerce_value(value, type)
+        case type
+        when :string
+          value.to_s
+        when :integer
+          value.to_i
+        when :float
+          value.to_f
+        when :boolean
+          %w[true 1 yes on].include?(value.to_s.downcase)
+        when :array
+          parse_array(value)
+        when :hash
+          parse_hash(value)
+        when :symbol
+          value.to_sym
+        else
+          value
+        end
+      end
+
+      def parse_array(value)
+        return [] if value.nil? || value.empty?
+
+        # Try to parse as JSON first
+        begin
+          parsed = JSON.parse(value)
+          return parsed if parsed.is_a?(Array)
+        rescue JSON::ParserError
+          # Fall back to comma-separated
+        end
+
+        value.split(',').map(&:strip)
+      end
+
+      def parse_hash(value)
+        return {} if value.nil? || value.empty?
+
+        begin
+          parsed = JSON.parse(value)
+          return parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      def validate_var!(name, value)
+        setting = settings[name]
+        return unless setting && setting[:validates]
+
+        validators = setting[:validates]
+
+        # Use ActiveModel validations if available
+        if defined?(ActiveModel::Validations) && validator_class
+          # The value being validated in place of the stored one; the others as they are, which rules that read
+          # another var need. ActiveModel cannot run one attribute's validators alone and keep their `if:`/`unless:`
+          # (`validate(name)` would take `name` for a validation context), so all run and this var's errors are read.
+          instance = validator_class.new
+          instance.public_send("#{name}=", value)
+          instance.valid?
+
+          attribute_errors = instance.errors[name]
+
+          if attribute_errors.any?
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} #{attribute_errors.join(', ')}"
+          end
+          return
+        end
+
+        # Run simple validations (when ActiveModel is not available)
+        # Presence validation
+        if validators[:presence] && (value.nil? || value.to_s.empty?)
+          raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} can't be blank"
+        end
+
+        # Length validation
+        if validators[:length] && value
+          length_opts = validators[:length]
+          length = value.to_s.length
+
+          if length_opts[:minimum] && length < length_opts[:minimum]
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} is too short (minimum is #{length_opts[:minimum]} characters)"
+          end
+
+          if length_opts[:maximum] && length > length_opts[:maximum]
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} is too long (maximum is #{length_opts[:maximum]} characters)"
+          end
+
+          if length_opts[:in] && !length_opts[:in].include?(length)
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} is the wrong length (should be #{length_opts[:in]} characters)"
+          end
+        end
+
+        # Format validation
+        if validators[:format] && value
+          format_opts = validators[:format]
+          format_regex = format_opts.is_a?(Hash) ? format_opts[:with] : format_opts
+          unless value.to_s.match?(format_regex)
+            message = format_opts.is_a?(Hash) && format_opts[:message] ? format_opts[:message] : "is invalid"
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} #{message}"
+          end
+        end
+
+        # Inclusion validation
+        if validators[:inclusion] && value
+          inclusion_opts = validators[:inclusion]
+          inclusion_values = inclusion_opts.is_a?(Hash) ? inclusion_opts[:in] : inclusion_opts
+          unless inclusion_values.include?(value)
+            raise ValidationError, "#{name.to_s.capitalize.gsub('_', ' ')} is not included in the list"
+          end
+        end
+      end
+
+      def validate!
+        # With ActiveModel: every var's rules at once, every failure in one error
+        if defined?(ActiveModel::Validations) && validator_class
+          instance = validator_class.new
+          raise ValidationError, instance.errors.full_messages.join(", ") unless instance.valid?
+
+          return
+        end
+
+        # Without it: the simple validations, var by var
+        settings.each do |name, config|
+          next unless config[:validates]
+
+          validate_var!(name, get_value(name))
+        end
+      end
+
+      def all
+        settings.keys.each_with_object({}) do |name, hash|
+          hash[name] = get_value(name)
+        end
+      end
+
+      def to_h
+        all
+      end
+    end
+  end
+end

data/lib/typed_env/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TypedEnv
+  VERSION = "1.0.0"
+end

data/lib/typed_env.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "typed_env/version"
+require_relative "typed_env/base"
+
+module TypedEnv
+  class Error < StandardError; end
+end

data/sig/typed_env.rbs

@@ -0,0 +1,4 @@
+module TypedEnv
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: typed_env
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dmitry Arkhipov
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: TypedEnv provides a clean DSL for managing environment variables with
+  type coercion, validations, and default values
+email:
+- d.arkhipov@ekzo.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/typed_env.rb
+- lib/typed_env/base.rb
+- lib/typed_env/version.rb
+- sig/typed_env.rbs
+homepage: https://github.com/ekzo-dev/typed_env
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ekzo-dev/typed_env
+  changelog_uri: https://github.com/ekzo-dev/typed_env/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ekzo-dev/typed_env/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Type-safe environment variables management for Ruby applications
+test_files: []