Validate and coerce env vars against a schema, listing errors
Environment variables are always strings, and a missing or mistyped one usually shows up hours later as NaN in a log or a server listening on port "80 ". Most teams therefore validate process.env once at startup against a small schema and crash early with a list of everything that is wrong.
Implement parseEnv(schema, env). It reads the keys described by schema from env, converts each one to its declared type, and either returns the typed config or every problem it found.
parseEnv(schema, env)
// => { ok: true, value: { ...typed config } }
// => { ok: false, errors: [{ key, code }, ...] }
schema is a flat object. Each key names an environment variable, and its value is a rule:
{ type: 'string' | 'number' | 'boolean' | 'enum', default?: any, values?: string[] }
values is required for 'enum' and must be a non-empty array.type, or an 'enum' rule has no non-empty values array, throw a TypeError. Check this before reading env.For each key of schema, in order:
raw = env[key]. If it is not a string, or it is blank after trim(), the variable is missing. A missing variable uses the rule’s default as-is (no conversion) if the rule has a default property, even if that default is null. Otherwise record { key, code: 'missing' }.raw and convert it:
'string': the trimmed string.'number': an optional -, one or more digits, and optionally a . followed by one or more digits (for example '8080', '-0.25', '007'). Convert with Number. Anything else ('1e3', '0x1F', '12px', '.5', 'Infinity') records { key, code: 'invalid_number' }.'boolean': 'true', 'yes', '1' give true; 'false', 'no', '0' give false. Case does not matter. Anything else records { key, code: 'invalid_boolean' }.'enum': the trimmed string if it is exactly one of values (case-sensitive). Otherwise record { key, code: 'invalid_enum' }.{ ok: true, value }, where value has exactly the schema’s keys.{ ok: false, errors } with one error per failing key, in schema order. Do not stop at the first error.env that the schema does not mention are ignored. Never mutate env or schema.const schema = {
PORT: { type: 'number', default: 3000 },
NODE_ENV: { type: 'enum', values: ['development', 'production', 'test'] },
ENABLE_CACHE: { type: 'boolean', default: false },
API_URL: { type: 'string' },
};
parseEnv(schema, {
PORT: ' 8080 ',
NODE_ENV: 'production',
ENABLE_CACHE: 'YES',
API_URL: 'https://api.example.com',
HOME: '/root',
});
// => { ok: true, value: { PORT: 8080, NODE_ENV: 'production', ENABLE_CACHE: true, API_URL: 'https://api.example.com' } }
parseEnv(schema, { NODE_ENV: 'test', API_URL: 'http://localhost' });
// => { ok: true, value: { PORT: 3000, NODE_ENV: 'test', ENABLE_CACHE: false, API_URL: 'http://localhost' } }
parseEnv(schema, { PORT: '80px', NODE_ENV: 'Production', ENABLE_CACHE: 'on' });
// => { ok: false, errors: [
// { key: 'PORT', code: 'invalid_number' },
// { key: 'NODE_ENV', code: 'invalid_enum' },
// { key: 'ENABLE_CACHE', code: 'invalid_boolean' },
// { key: 'API_URL', code: 'missing' },
// ] }
parseEnv({ LOG_LEVEL: { type: 'level' } }, {}); // throws TypeError