@atom-forge/env-reader

Type-safe environment variable reader for TypeScript. Reads, parses, and validates environment variables at startup — so your app fails fast if the environment is misconfigured, not at runtime.

Installation

npm install @atom-forge/env-reader

Usage

import { EnvReader, asReadonly } from "@atom-forge/env-reader";
import path from "path";

const env = new EnvReader(path.resolve(__dirname, "../"));

const config = asReadonly({
    app: {
        env: env.oneOf("APP_ENV", ["dev", "prod", "test"], "prod"),
    },
    database: {
        connectionString: env.string("DATABASE_URL"),
        maxPool: env.int("DB_POOL_MAX", 20),
    },
    auth: {
        secret: env.string("JWT_SECRET"),
        expiresIn: env.int("JWT_EXPIRATION", 60 * 60 * 8),
    },
});

API

new EnvReader(projectRoot: string)

Instantiate with an absolute path to the project root. Used for resolving file() and dir() paths.

Methods

| Method | Returns | Description | |---|---|---| | string(key, default?, trim?) | string | Reads a string. Trims whitespace by default. | | int(key, default?, radix?) | number | Parses an integer. Radix defaults to 10. | | float(key, default?) | number | Parses a floating-point number. | | boolean(key, default?) | boolean | Parses true/false, yes/no, 1/0 (case-insensitive). | | url(key, default?) | URL | Validates and returns a URL object. | | regex(key, default?) | RegExp | Validates and returns a RegExp object. | | oneOf(key, values, default?) | T | Validates the value is one of the allowed strings. | | list(key, parser, default?, separator?) | T[] | Splits by separator (default ,) and parses each item. | | file(key, default?, onMissing?, stayInProject?) | string | Resolves an absolute file path. | | dir(key, default?, onMissing?, stayInProject?) | string | Resolves an absolute directory path. |

If a variable is missing and has no default, the method throws immediately.

asReadonly<T>(value: T): DeepReadonly<T>

Wraps a config object in a DeepReadonly type. Zero runtime cost — pure TypeScript type cast.

const config = asReadonly({ db: { host: "localhost" } });
config.db.host = "other"; // TS error

list example

// ALLOWED_PORTS=80,443,3000
const ports = env.list("ALLOWED_PORTS", v => parseInt(v, 10));
// → [80, 443, 3000]

file / dir parameters

• onMissing: true (default) throws on missing path, false returns the path silently, or a (path) => void callback.
• stayInProject: true (default) prevents path traversal outside the project root.