Nodejs Typescript Environment Validator and Loader
Tired of repeating (or copy/paste) the same environment variable handling and validation over and over again?
envrr
aims to help with that!
It does so by using an Environment
typed and decorated class via a small build step
npm install --save envrr
We start by firstly defining our env.ts
e.g.
// <cwd>/src/env.ts
import { EnvVariable, IsPartOfEnum, DefaultsTo, IsCronString } from 'envrr';
export class Environment {
@EnvVariable('APPLICATION_NAME')
applicationName: string;
@EnvVariable('PORT')
@DefaultsTo(3000)
port: number;
@EnvVariable('LOG_LEVEL')
@IsPartOfEnum(['debug', 'info', 'warn', 'error'])
logLevel: string;
redis: RedisConnectionConfig;
prometheus: PrometheusConfig;
@EnvVariable('SECRET_EXPIRE_AT')
secretExpireAt: Date;
@EnvVariable('NOTIFY_PERIOD')
@IsCronString()
notifyPeriod: string;
}
class RedisConnectionConfig {
@EnvVariable('REDIS_HOST')
host: string;
@EnvVariable('REDIS_PORT')
port: number;
@EnvVariable('REDIS_USERNAME')
username: string;
@EnvVariable('REDIS_PASSWORD')
password: string;
@EnvVariable('REDIS_INDEXES')
indexes: string[];
}
class PrometheusConfig {
@EnvVariable('PROMETHEUS_ENABLED')
@DefaultsTo(false)
enabled: boolean;
@EnvVariable('PROMETHEUS_HOST')
host: string;
@EnvVariable('PROMETHEUS_PORT')
port: number;
@EnvVariable('PROMETHEUS_DEFAULT_QUANTILES')
defaultQuantiles?: number[];
flags?: PrometheusFlags;
}
class PrometheusFlags {
@EnvVariable('PROMETHEUS_ENABLED_ENDPOINTS')
enabledEndpoints?: string[];
@EnvVariable('PROMETHEUS_ENABLED_USER_IDS')
enabledUserIds?: number[];
}
Note: the name of the file nor the location is not important (as its target can be changed within the build step); the important part is to export
the Environment
class.
The type definition of the Environment
class must be built in order to survive past runtime.
We use tparserr
to translate the type definition into a .json
file, and we do so as below:
tparserr generate --includeOnlyExports --enableDecorators -f=<env.ts target path> -o=<env.json output path>
By default envrr
looks for the env.json
type descriptions under <cwd>/env.json
- this however can be changed via adjusting the targetPath
passed to the envrr
initialisation.
Following the example above, we can build the types by either manually running:
npx tparserr generate --includeOnlyExports --enableDecorators -f=./src/env.ts -o=./env.json
or simply adding it as a package.json
script and hook it before out tsc
build.
e.g.
{
// ...
"scripts": {
"build-env": "tparserr generate --includeOnlyExports --enableDecorators -f=./src/env.ts -o=./env.json",
"build": "npm run build-env && tsc"
}
// ...
}
It is recommended to initialise envrr
as soon as possible during the app startup in order to validate if the whole environment corresponds to the typed Environment
; after which it can be used/reused throughout the application without having to initialize
(singleton).
// <cwd>/src/index.ts
process.env.APPLICATION_NAME = 'test';
process.env.PORT = '3000';
process.env.LOG_LEVEL = 'debug';
process.env.REDIS_HOST = 'localhost';
process.env.REDIS_PORT = '6379';
process.env.REDIS_USERNAME = 'user';
process.env.REDIS_PASSWORD = 'password';
process.env.REDIS_INDEXES = 'abc, def, ghi';
process.env.PROMETHEUS_ENABLED = 'true';
process.env.PROMETHEUS_HOST = 'localhost';
process.env.PROMETHEUS_PORT = '9090';
process.env.PROMETHEUS_DEFAULT_QUANTILES = '0.5, 0.9, 0.99';
process.env.SECRET_EXPIRE_AT = '2025-05-01 12:00:00';
process.env.NOTIFY_PERIOD = '* */1 * * *';
import { Environment } from './env';
import { Enver } from 'envrr';
(async function main() {
await Enver.initialize<Environment>();
const env = Enver.getEnv<Environment>();
// const env: Environment
const port = Enver.get<Environment, 'port'>('port');
// const port: number
const hasRedisHost = Enver.has('redis.host');
// const hasRedisHost: boolean
const redisOpts = Enver.get<Environment, 'redis'>('redis');
// const redisOpts: RedisConnectionConfig
const redisPort = Enver.get<Environment, 'redis', 'port'>('redis', 'port');
// const redisPort: number
const prometheusDefaultQuantiles = Enver.get<
Environment,
'prometheus',
'defaultQuantiles'
>('prometheus', 'defaultQuantiles');
// const prometheusDefaultQuantiles: number[]
const prometheusEnabledUserIds = Enver.get<
Environment,
'prometheus',
'flags',
'enabledUserIds'
>('prometheus', 'flags', 'enabledUserIds');
// const prometheusEnabledUserIds: number[]
const secretExpireAt = Enver.get<Environment, 'secretExpireAt'>(
'secretExpireAt'
);
// const secretExpireAt: Date
})().catch(console.error);
Note: in case the environment is invalid, envrr
will throw error
s in the order of validation/type description (fail-fast)
initialize
- used to initialiseenvrr
getEnv
- used to get the whole loaded environmenthas
- checks whether a json path (e.g.nesting.key.otherKey
) to an environment variable existsget
- used to get specific env variable values
@EnvVariable
- required on anyEnvironment
property that requires validation/loading@IsPartOfEnum
- used to restrict allowed values to a predefined enum@DefaultsTo
- used to default env variables if not present@IsCronString
- validates the string to be an either 5 char or 6 char cron string
export interface IEnverConfig {
// by default it points to <cwd>/env.json for its' to be loaded type definitions
targetPath?: string;
}
Any improvement ideas/suggestions; feel free to open an issue :)
This library is licensed under the Apache 2.0 License