api.service.Dotenv

This service provides methods for reading .env files.

Supported file syntax

• Files are assumed to contain text encoded in UTF-8 character set.

• They are processed line by line.

• Empty lines and lines starting with # are ignored.

• Other lines are assumed to contain assignments like

  key=value

• Leading and trailing whitespace per line is ignored.

• Whitespace before or after the assignment operator is ignored, too. Line breaks are not supported there.

• The key must be a sequence of non-whitespace characters unless it is wrapped in quotes.

• The value may contain inner whitespace. Leading or trailing whitespace is ignored.

  • The value ends at first # assumed to start a comment ending at end of line.

• The value may be wrapped in single or double quotes.

  • Whitespace inside the quotes is retained as given. This includes line breaks.
  • Comments starting with a # may follow the closing quote until end of line.

• Values may refer to previously defined variables using their keys prefixed with a single dollar sign. Variable references are replaced with referenced variables' values.

  • The name of referenced variable may be wrapped in a pair of curly braces to clearly separate it from follow-up characters that may be unintentionally considered part of referenced variable's name.

    FOO="${MODE}_STATE"

  • The referenced variable's name, when wrapped in curly braces, may be followed by a colon and one of these modifiers:

    • -default may be used to replace the reference with default if named variable has no value (which includes the empty string as value).

      RESULT="${VALUE:-foo}"

    • +alt may be used to replace the reference with alt instead of the named variable's value unless it has no value (which again includes the empty string).

      STATE="${RESULT:+ready}"

Static methods

readFile()

This method reads and parses the content of file named in first argument. The file is assumed to define variables in dotenv syntax based on the rules provided above.

A pre-existing set of variables can be provided in optional second argument. They can be additionally referenced in values read from the file.

const valuesA = await readFile( filename );
const valuesB = await readFile( filename, valuesA );

read()

This method reads and parses the content of .env file in project folder of current runtime and merges it with the runtime's environment variables.

The result of reading the file is cached so that multiple invocations of this method provide the same promise every time.