LemonCore.Config.Helpers (lemon_core v0.1.0)

View Source

Helper functions for configuration resolution.

Inspired by Ironclaw's config/helpers.rs, these utilities provide consistent environment variable handling with proper type conversion and default value support.

Usage

alias LemonCore.Config.Helpers

# Get optional env var
api_key = Helpers.get_env("OPENAI_API_KEY")

# Get with default
port = Helpers.get_env_int("PORT", 4000)

# Parse boolean
debug = Helpers.get_env_bool("DEBUG", false)

# Get required var (raises if missing)
database_url = Helpers.require_env!("DATABASE_URL")

Summary

Functions

get_env(key)

Gets an optional environment variable.

get_env(key, default)

Gets an environment variable with a default value.

get_env_atom(key, default)

Gets an environment variable as an atom.

get_env_bool(key, default)

Gets an environment variable as a boolean.

get_env_bytes(key, default)

Gets an environment variable as bytes.

get_env_duration(key, default)

Gets an environment variable as a duration in milliseconds.

get_env_float(key, default)

Gets an environment variable as a float.

get_env_int(key, default)

Gets an environment variable as an integer.

get_env_list(key, delimiter \\ ",")

Gets an environment variable as a list of strings.

get_feature_env(feature_flag, key, default \\ nil)

Conditionally gets an environment variable based on a feature flag.

parse_bytes(value, default)

Gets an environment variable as bytes.

parse_duration(value, default)

Parses a duration string into milliseconds.

require_env!(key)

Requires an environment variable to be set.

require_env!(key, hint)

Requires an environment variable to be set with a custom error message.

Functions

get_env(key)

@spec get_env(String.t()) :: String.t() | nil

Gets an optional environment variable.

Returns nil if the variable is not set or is empty.

Examples

iex> Helpers.get_env("NONEXISTENT_VAR")
nil

iex> System.put_env("EXISTING_VAR", "value")
iex> Helpers.get_env("EXISTING_VAR")
"value"

get_env(key, default)

@spec get_env(String.t(), String.t()) :: String.t()

Gets an environment variable with a default value.

Examples

iex> Helpers.get_env("NONEXISTENT", "default")
"default"

get_env_atom(key, default)

@spec get_env_atom(String.t(), atom()) :: atom()

Gets an environment variable as an atom.

The value is converted to a snake_case atom. Returns the default if not set.

Examples

iex> System.put_env("LOG_LEVEL", "debug")
iex> Helpers.get_env_atom("LOG_LEVEL", :info)
:debug

get_env_bool(key, default)

@spec get_env_bool(String.t(), boolean()) :: boolean()

Gets an environment variable as a boolean.

The following values are considered true: "true", "1", "yes", "on" The following values are considered false: "false", "0", "no", "off" Returns the default if the variable is not set or empty.

Examples

iex> System.put_env("DEBUG", "true")
iex> Helpers.get_env_bool("DEBUG", false)
true

iex> System.put_env("ENABLED", "1")
iex> Helpers.get_env_bool("ENABLED", false)
true

iex> System.put_env("DISABLED", "no")
iex> Helpers.get_env_bool("DISABLED", true)
false

get_env_bytes(key, default)

@spec get_env_bytes(String.t(), integer()) :: integer()

Gets an environment variable as bytes.

Examples

iex> System.put_env("MAX_SIZE", "10MB")
iex> Helpers.get_env_bytes("MAX_SIZE", 1024)
10485760

get_env_duration(key, default)

@spec get_env_duration(String.t(), integer()) :: integer()

Gets an environment variable as a duration in milliseconds.

Examples

iex> System.put_env("TIMEOUT", "30s")
iex> Helpers.get_env_duration("TIMEOUT", 5000)
30000

get_env_float(key, default)

@spec get_env_float(String.t(), float()) :: float()

Gets an environment variable as a float.

Returns the default if the variable is not set, empty, or cannot be parsed.

get_env_int(key, default)

@spec get_env_int(String.t(), integer()) :: integer()

Gets an environment variable as an integer.

Returns the default if the variable is not set, empty, or cannot be parsed.

Examples

iex> System.put_env("PORT", "8080")
iex> Helpers.get_env_int("PORT", 4000)
8080

iex> Helpers.get_env_int("NONEXISTENT", 4000)
4000

iex> System.put_env("BAD_PORT", "not_a_number")
iex> Helpers.get_env_int("BAD_PORT", 4000)
4000

get_env_list(key, delimiter \\ ",")

@spec get_env_list(String.t(), String.t()) :: [String.t()]

Gets an environment variable as a list of strings.

Values are split by the given delimiter (default: ","). Empty values are filtered out.

Examples

iex> System.put_env("ALLOWED_HOSTS", "localhost,example.com")
iex> Helpers.get_env_list("ALLOWED_HOSTS")
["localhost", "example.com"]

get_feature_env(feature_flag, key, default \\ nil)

@spec get_feature_env(String.t(), String.t(), String.t() | nil) :: String.t() | nil

Conditionally gets an environment variable based on a feature flag.

If the feature flag is enabled, returns the value (or default if not set). If disabled, returns nil.

Examples

iex> System.put_env("FEATURE_X", "true")
iex> System.put_env("FEATURE_X_API_KEY", "secret")
iex> Helpers.get_feature_env("FEATURE_X", "FEATURE_X_API_KEY")
"secret"

iex> Helpers.get_feature_env("DISABLED_FEATURE", "SOME_KEY")
nil

parse_bytes(value, default)

@spec parse_bytes(String.t() | nil, integer()) :: integer()

Gets an environment variable as bytes.

Supports: B, KB, MB, GB (case insensitive, optional space) Returns the default if parsing fails.

Examples

iex> Helpers.parse_bytes("10MB", 0)
10485760

iex> Helpers.parse_bytes("1.5 GB", 0)
1610612736

parse_duration(value, default)

@spec parse_duration(String.t() | nil, integer()) :: integer()

Parses a duration string into milliseconds.

Supports: ms, s, m, h, d (milliseconds, seconds, minutes, hours, days) Returns the default if parsing fails.

Examples

iex> Helpers.parse_duration("30s", 0)
30000

iex> Helpers.parse_duration("5m", 0)
300000

iex> Helpers.parse_duration("invalid", 1000)
1000

require_env!(key)

@spec require_env!(String.t()) :: String.t()

Requires an environment variable to be set.

Raises an ArgumentError if the variable is not set or empty.

Examples

iex> System.put_env("REQUIRED", "value")
iex> Helpers.require_env!("REQUIRED")
"value"

iex> Helpers.require_env!("NONEXISTENT")
** (ArgumentError) Missing required environment variable: NONEXISTENT

require_env!(key, hint)

@spec require_env!(String.t(), String.t()) :: String.t()

Requires an environment variable to be set with a custom error message.

Examples

iex> System.put_env("API_KEY", "secret")
iex> Helpers.require_env!("API_KEY", "Please set API_KEY in your environment")
"secret"