Documentation / @andrew_l/toolkit / EnvParser

Interface: EnvParser

Environment variable parser

Properties

isDevelopment

readonly isDevelopment: boolean

true when NODE_ENV, or Vite MODE without it, is development.

---

isProduction

readonly isProduction: boolean

true when NODE_ENV, or Vite MODE without it, is production.

---

isStage

readonly isStage: boolean

true when NODE_ENV, or Vite MODE without it, is stage.

---

isTest

readonly isTest: boolean

true when NODE_ENV, or Vite MODE without it, is test.

Methods

bool()

bool(key, defaultValue?): boolean

Reads a boolean: "true" or "false".

Parameters

key

string

Environment variable name.

defaultValue?

boolean

Returned when the value is missing, empty or invalid.

Returns

boolean

The parsed boolean or defaultValue.

Example

const DEBUG = env.bool('DEBUG');

---

decimal()

decimal(key, digits?, defaultValue?): number

Reads a number, including Infinity.

Parameters

key

string

Environment variable name.

digits?

number

Decimal places to round to, applied to defaultValue as well.

defaultValue?

number

Returned when the value is missing, empty or invalid.

Returns

number

The parsed number or defaultValue, rounded to digits when given.

Example

const RATIO = env.decimal('RATIO', 2, 0.5);

---

int()

int(key, defaultValue?): number

Reads a safe integer.

Parameters

key

string

Environment variable name.

defaultValue?

number

Returned when the value is missing, empty or invalid.

Returns

number

The parsed integer or defaultValue.

Example

const PORT = env.int('PORT', 3000);

---

json()

Call Signature

json<T>(key, defaultValue?): T

Reads a JSON value.

Type Parameters

T

T = any

Parameters

key

string

Environment variable name.

defaultValue?

T

Returned when the value is missing, empty or invalid.

Returns

T

The parsed value or defaultValue.

Example

const CREDS = env.json<{ token: string }>('CREDS');

Call Signature

json<T>(key, defaultValue?): T | null

Type Parameters

T

T = any

Parameters

key

string

defaultValue?

T | null

Returns

T | null

---

list()

Call Signature

list<T>(key, itemType, defaultValue?): ListTypeNameToType<T>[]

Reads a comma-separated list. Empty items are dropped, items that fail to parse are skipped with a warning.

Type Parameters

T

T extends keyof ListTypeMap

Parameters

key

string

Environment variable name.

itemType

T

Item type name, allowed values or item parser.

defaultValue?

ListTypeNameToType<T>[]

Returned when the key is missing or no item could be parsed.

Returns

ListTypeNameToType<T>[]

The parsed items, [] when the value has no items (e.g. "" or " , "), or defaultValue.

Example

env.list('ROLES', 'string');                        // string[]
env.list('PORTS', 'int');                           // number[]
env.list('LEVELS', ['debug', 'info'] as const);     // ('debug' | 'info')[]
env.list('ORIGINS', value => new URL(value));       // URL[]

Call Signature

list<V>(key, allowedValues, defaultValue?): V[number][]

Type Parameters

V

V extends readonly string[]

Parameters

key

string

allowedValues

V

defaultValue?

V[number][]

Returns

V[number][]

Call Signature

list<T>(key, parser, defaultValue?): T[]

Type Parameters

T

T

Parameters

key

string

parser

EnvValueParser<T>

defaultValue?

T[]

Returns

T[]

---

oneOf()

oneOf<T, D>(key, allowedValues, defaultValue?): D | T[number]

Reads one of allowedValues, typed as their union.

Type Parameters

T

T extends readonly string[]

D

D = undefined

Parameters

key

string

Environment variable name.

allowedValues

T

Accepted values.

defaultValue?

D

Returned when the value is missing, empty or not listed.

Returns

D | T[number]

The matched value or defaultValue.

Example

const level = env.oneOf('LOG_LEVEL', ['debug', 'info', 'warn'], 'info');
// level: 'debug' | 'info' | 'warn'

---

parse()

parse<T, D>(key, parser, defaultValue?): T | D

Reads a value through a custom parser.

Type Parameters

T

T

D

D = undefined

Parameters

key

string

Environment variable name.

parser

EnvValueParser<T>

Signals failure by returning undefined or throwing.

defaultValue?

D

Returned when the value is missing, empty or fails to parse.

Returns

T | D

The parsed value or defaultValue.

Example

const url = env.parse('DATABASE_URL', value => new URL(value));

---

string()

string(key, defaultValue?): string

Reads a raw string. The value is not trimmed and an empty value is returned as is.

Parameters

key

string

Environment variable name.

defaultValue?

string

Returned when the key is missing.

Returns

string

The raw value or defaultValue.

Example

const API_KEY = env.string('API_KEY', 'test_key');