@6cat/env

Create javascript objects from environment variables. If you are using TypeScript, the result is fully typed as well.

Warning While environment variables names can theoretically contain any character besides =, there are many tools that do not support anything besides A-Za-z0-9_ and it's therefore recommended that you limit yourself to those characters.

Usage

import { parseEnvironment, string, number } from "@6cat/env";

const env = parseEnvironment({
  auth: {
    bearerToken: string({ default: "" }),
    requestLimit: number,
  },
});

console.log(env.auth.bearerToken);

This would read and log the value from environment variables named AUTH_BEARER_TOKEN, AUTH_BEARERTOKEN, auth_bearerToken, or auth.bearerToken (this last form is discouraged).

parseEnvironment

Read environment variables

env: Environment to use (default: process.env)

profiles: Optional profiles

If specified, environment variables that start with these values will override any other keys. The first array value has the highest priority. Profile variables can use the optional prefix _ or %.

For example, this allows for configuring multiple environments:

let env = parseEnvironment({ endpoint: string }, { profiles: ["dev"] });

ENDPOINT=http://service.prod
_DEV_ENDPOINT=http://service.dev
_TEST_ENDPOINT=http://localhost:2000

argv: Whether command line arguments will be parsed as well

If true, in addition to environment variables, command line arguments will be parsed as well:

node app.js --service.name=foo -Dservice.version=v1

let env = parseEnvironment(
  { service: { name: string, version: string } },
  { argv: true }
);

If a string is configured, it will be prefixed to any argument provided. (note that this will effectively disable profile support for command line arguments)

node action.js --name=foo

let env = parseEnvironment({ input: { name: string } }, { argv: "input" });

Types

The following types are included in the package.

array

Read an array

Array values are comma separated by default:

EXAMPLE_ARRAY=value,other value

If you want to split values into multiple environment variables, you can use indexed entries:

EXAMPLE_ARRAY_0=value
EXAMPLE_ARRAY_1=other value
exampleArray[2]=alternative syntax

You can create arrays of complex objects, but it that case you can only use indexed entries:

let env = parseEnvironment({ values: array({ url: string }) });

values_0_url=https://foo
values_1_url=https://bar

boolean

Read a boolean

Similar to YAML, supported formats are true, y, yes, and on.

default: A default value in case no environment variables is defined (default: undefined)

required: Whether the value is required, in which case an error will be thrown if no value is provided (default: false)

number

Read a number

default: A default value in case no environment variables is defined (default: undefined)

required: Whether the value is required, in which case an error will be thrown if no value is provided (default: false)

record

Read a record

Strings will always be converted to lowercase when used as keys, to avoid surprises when switching keys between upper and lowercase.

For example,

const env = parseEnvironment({ values: record(string, string) });
console.log(env.values["test"]);

Will read environment variables VALUES_TEST and values.test.

string

Read a string

default: A default value in case no environment variables is defined (default: undefined)

required: Whether the value is required, in which case an error will be thrown if no value is provided (default: false)

trim: Whether whitespace will be trimmed from the value (default: true)

trailingSlash: Whether a trailing slash is automatically added or removed from the value (default: no change)

Creating custom types

The easiest way to add support for a new type is by using the Parser.forValue method. For example, if you want to parse URLs:

import { parseEnvironment, Parser } from "@6cat/env";

function url() {
  return Parser.forValue((value, ctx) => (value ? new URL(value) : undefined));
}

const env = parseEnvironment({
  endpoint: url,
});

If no environment variables matches, a value of undefined will be passed to the parser, allowing you to set a default value.