glimr/config

Unified Configuration

Every module in the framework needs config values — session secrets, database URLs, feature flags — but scattering simplifile.read and tom.parse calls everywhere would be a mess. This module reads all config/*.toml files once at boot, caches the merged result in persistent_term, and gives the rest of the codebase a clean dot-path API like config.get_string("session.cookie"). Environment variable interpolation (${VAR} and ${VAR:-fallback}) is resolved transparently so secrets never live in TOML files.

Values

app_port

</>

pub fn app_port() -> Int

New projects should just work out of the box without requiring a .env file, so this defaults to 8000 if APP_PORT isn’t set. Production deployments override it via the env var without touching any config files.

clear_cache

</>

pub fn clear_cache() -> Nil

Tests that exercise different config scenarios need to start fresh between runs. Without clearing, the persistent_term cache would serve stale values from the previous test case and produce confusing failures.

dev_proxy_port

</>

pub fn dev_proxy_port() -> Int

The dev proxy sits in front of the app server to inject live-reload scripts. It defaults to 8001 — one above the app port — so both can run simultaneously without conflicts during development.

get_bool

</>

pub fn get_bool(path: String) -> Bool

Panicking bool getter for feature flags and toggles that must be explicitly configured — like auto_compile or auto_gen. A crash on missing values forces developers to set them in their TOML rather than silently defaulting.

get_bool_list

</>

pub fn get_bool_list(path: String) -> List(Bool)

Bool list getter — included for completeness with the other list getters, though it’s rare to need an array of booleans in practice. Returns empty on missing keys for consistency with the string and int variants.

get_bool_or

</>

pub fn get_bool_or(path: String) -> Result(Bool, Nil)

Safe bool getter for optional config where a missing value is fine — the caller decides the default. Unlike strings and ints, bools don’t support env interpolation since TOML booleans are unambiguous.

get_int

</>

pub fn get_int(path: String) -> Int

Panicking int getter for values that must exist, like port numbers or pool sizes. Handles both native TOML integers and string values containing ${VAR} references — because hosting providers often expose numeric config as strings through env vars.

get_int_list

</>

pub fn get_int_list(path: String) -> List(Int)

Int list getter for config values like allowed port ranges or rate limit tiers. Returns empty on missing keys so callers can treat absence as “no restrictions” without special-casing.

get_int_or

</>

pub fn get_int_or(path: String) -> Result(Int, Nil)

Safe int getter that tries native TOML ints first, then falls back to parsing a string with env interpolation. The two-phase lookup matters because developers might write pool_size = 10 or pool_size = "${POOL_SIZE}" and both should work without them thinking about it.

get_string

</>

pub fn get_string(path: String) -> String

The panicking variant for callers that consider a missing config value a hard stop — like the session module needing its secret key. If the key is absent or the env var isn’t set, you’ll get a crash at boot rather than a subtle bug at runtime.

get_string_list

</>

pub fn get_string_list(path: String) -> List(String)

Accepts both TOML arrays and single string values, wrapping the latter in a list automatically. This means developers can write allowed = "admin" instead of allowed = ["admin"] when there’s only one value, and upgrade to an array later without breaking anything.

get_string_or

</>

pub fn get_string_or(path: String) -> Result(String, Nil)

The safe variant for callers that want to handle missing config gracefully — like optional features that fall back to defaults. Returns Error(Nil) if the key doesn’t exist or an env var can’t be resolved, so you can chain it with result.unwrap or result.try.

get_table

</>

pub fn get_table(
  path: String,
) -> Result(dict.Dict(String, tom.Toml), Nil)

Driver modules like db/driver and cache/driver need access to the raw TOML table so they can iterate over sub-keys and parse each entry their own way. The simple scalar getters above aren’t enough when the config is a dict of named connections or stores.

load

</>

pub fn load() -> Nil

The entire config system hinges on this running once at boot before anything else touches config values. It loads .env first (so TOML files can reference those vars), then reads every .toml in config/ and merges them into one dict keyed by filename — session.toml becomes “session”, so get_string("session.cookie") just works.