Envapter

Envapter is the functional entry point to envapt. Every reader comes two ways: a static method for one-off reads, and an instance method for when you hold a new Envapter() or extend it. Both read from the same parsed cache.

import { Envapter } from 'envapt';

// static, for a one-off read
const port = Envapter.getNumber('PORT', 3000);
      
const port: number

// instance, when you hold a reference
const env = new Envapter();
const apiUrl = env.get('API_URL', 'http://localhost');
       
const apiUrl: string

Primitives

Five readers cover the primitive types. Each parses the raw string and returns the matching type.

const name = Envapter.get('APP_NAME', 'envapt'); // string
const port = Envapter.getNumber('PORT', 3000); // number
const debug = Envapter.getBoolean('DEBUG', false); // boolean
const maxBytes = Envapter.getBigInt('MAX_UPLOAD_BYTES', 0n); // bigint
const key = Envapter.getSymbol('KEY', Symbol.for('envapt:key')); // symbol

getBoolean reads 1, yes, true, on as true and 0, no, false, off as false, case-insensitively. Anything else uses the fallback.

Fallbacks shape the return type

A fallback supplies the default value and removes undefined from the return type. With a fallback the return is T; without one it's T | undefined, so the type makes you handle the missing case.

const withFallback = Envapter.get('API_URL', 'http://localhost');
          
const withFallback: string

const noFallback = Envapter.get('API_URL');
         
const noFallback: string | undefined

Ordered keys

Any reader accepts an ordered list of keys instead of a single name. The first key with a present value wins, so an aliased or renamed variable falls back to its old name in one read. An empty value, or a whitespace-only value under strict, is skipped like an unset key.

// READONLY_URL if set, else DATABASE_URL, else the fallback
const db = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');
     
const db: string

Raw values

getRaw returns the string exactly as loaded, with no type conversion. It exists only as an instance method:

const raw = new Envapter().getRaw('DATABASE_URL');
     
const raw: string | undefined

Converters

For shapes beyond primitives, two readers take a converter:

• getUsing(key, token, fallback?) for built-in converter tokens (arrays, URLs, dates, durations, and more).
• getWith(key, fn, fallback?) for your own (raw, fallback) => T function.

const origins = Envapter.getUsing('CORS', Converters.array({ of: Converters.String }));
       
const origins: string[] | undefined

const retries = Envapter.getWith('RETRIES', (raw, fallback) => (raw ? Number(raw) : fallback), 3);
       
const retries: unknown

Fallbacks behave like the primitives, removing undefined from the return type. The Converters page covers every built-in token.

Template strings

resolve is a tagged template that inlines env values by key, and expands any ${VAR} references inside the resolved values.

// PGUSER=app, PGPASSWORD=secret, PGHOST=db.internal, PGDATABASE=myapp
const dsn = Envapter.resolve`postgres://${'PGUSER'}:${'PGPASSWORD'}@${'PGHOST'}/${'PGDATABASE'}`;
     
const dsn: string

See Templates for ${VAR} interpolation and cycle protection.

Fail-fast on missing values

require asserts that one or more keys are present and non-empty after template resolution, throwing an EnvaptError that names every missing key. A whitespace-only value counts as missing only under strict mode.

// Assuring all three keys are present at the start of the program, for example
Envapter.require('DATABASE_URL', 'API_KEY', 'SENTRY_DSN');

has returns boolean with the same missing semantics as getRequired. An ordered key list falls through to the first present key. It returns true exactly when a required read of the same key would find a value.

if (!Envapter.has('SENTRY_DSN')) {
    throw new Error('Set SENTRY_DSN in your .env before deploying.');
}

For a typed fail-fast that returns the parsed value, use getRequired:

const url = Envapter.getRequired('DATABASE_URL', Converters.Url);
     
const url: URL

getRequiredAll reads a whole group in one call and returns a typed record, throwing once with every missing key. A spec value is a token, an array() token, or a custom parser, and an optional casing ('camelCase', 'PascalCase', or 'kebab-case') renames the keys. Casing splits on underscores, so it expects the conventional SCREAMING_SNAKE env-var names:

const config = Envapter.getRequiredAll(
    {
        DATABASE_URL: Converters.Url,
        PORT: Converters.Number,
        FEATURE_FLAGS: (raw) => new Set(raw.split(','))
    },
    'camelCase'
);

config;
 
const config: {
    databaseUrl: URL;
    port: number;
    featureFlags: Set<string>;
}

They throw on a missing value instead of returning a fallback. See Strict mode for the global switch and how required reads relate to it.

Static vs instance

Statics suit scattered, one-off reads. Create an instance to carry an env reader as a dependency, or extend Envapter to group related config on one class.

class Config extends Envapter {
    readonly port = this.getNumber('PORT', 3000);
    readonly debug = this.getBoolean('DEBUG', false);
}

Static and instance reads hit the same cache.

Environment detection

Envapter also detects the current runtime environment and exposes it through the isProduction / isStaging / isDevelopment / isTest helpers. On Node, Bun, and Deno it auto-loads the matching .env files for that environment. The helpers, the Environment enum, and per-environment file selection are documented on Environment.