@bleed-believer/env

Typed access to environment variables, with a .env file as a fallback for process.env.

• Typed values: the type of each value is inferred from how the variable is declared.
• process.env wins: the .env file only provides the variables that process.env doesn't have.
• Lazy: nothing is read or validated until you call get.
• No dependencies: parsing is done by Node's built-in util.parseEnv.

Installation

npm install @bleed-believer/env

Requires Node.js 20.12 or later, and ESM (the package has no CommonJS build).

Quick start

import { Env } from '@bleed-believer/env';

export const env = new Env('.env', {
    variables: {
        host:  { rawName: 'APP_HOST',  required: true },
        port:  { rawName: 'APP_PORT',  required: true, callback: v => parseInt(v, 10) },
        debug: { rawName: 'APP_DEBUG', callback: v => v === 'true' },
        token: { rawName: 'APP_TOKEN' }
    }
});

env.get('host');    // string
env.get('port');    // number
env.get('debug');   // boolean
env.get('token');   // string | undefined
env.get('other');   // compile error: "other" isn't declared

Declaring variables

Each key in variables is the name you pass to get, and describes one environment variable:

| Property | Type | Description | | ---------- | ---------------------- | ----------------------------------------------------------------------- | | rawName | string | Name of the variable in process.env and in the .env file. | | required | boolean | When true, get throws if the variable isn't set in either source. | | callback | (value) => any | Transforms the raw string before it's returned by get. |

The value returned by get is typed as follows:

| Declaration | Callback receives | get returns | | ---------------------------- | ---------------------- | ------------------------ | | required: true | - | string | | optional | - | string \| undefined | | required: true + callback | string | the callback's return | | optional + callback | string \| undefined | the callback's return |

A callback on an optional variable also runs when the variable is missing, so it can provide a default:

port: { rawName: 'APP_PORT', callback: v => parseInt(v ?? '3000', 10) }

Declaring variables apart from the constructor

To keep the inferred types, declare the variables with satisfies, not with a type annotation:

import type { EnvVariables } from '@bleed-believer/env';
import { Env } from '@bleed-believer/env';

const variables = {
    host: { rawName: 'APP_HOST', required: true },
    port: { rawName: 'APP_PORT', required: true, callback: v => parseInt(v, 10) }
} satisfies EnvVariables;

const env = new Env('.env', { variables });
env.get('port');    // number

With an annotation (const variables: EnvVariables = ...), the declarations are lost: get accepts any name and returns unknown.

Where values come from

For each call to get, the variable rawName is looked up in this order:

1. process.env. An empty value (APP_HOST=) counts as set.
2. The .env file, only when the variable isn't in process.env. If process.env has it, the file isn't read.

Keeping the .env file as a fallback means the variables set by your deployment (Docker, Kubernetes, CI…) always win over a local file.

About the file:

• A relative path is resolved against process.cwd(), not against the file that creates the Env.
• A missing file isn't an error: the variables are just unset. Any other read error (e.g. EACCES, or EISDIR when the path is a directory) is thrown by get.
• The syntax is the one supported by util.parseEnv: comments, blank lines, single, double and backtick quotes, multiline quoted values and the export prefix. A leading BOM is ignored.

Caching

By default, the file is read and parsed again on every call to get, so changes to the file are picked up immediately. Set cacheable: true to read it only once:

const env = new Env('.env', {
    cacheable: true,
    variables: { /* ... */ }
});

With cacheable: true:

• The file is read on the first get that needs it, not in the constructor.
• A missing file is cached too.
• Read errors other than a missing file are never cached, so the next get tries again.
• process.env is never cached; changes to it are always visible.

Errors

Every error is thrown by get, when the variable is read:

| Situation | Message | | ------------------------------------------------ | --------------------------------------------------------------------- | | The name isn't declared in variables | The variable "port" isn't declared in the "variables" option | | A required variable is missing in both sources | The environment variable "APP_PORT" is required, but isn't set | | A callback throws | The callback of the variable "port" failed to process "APP_PORT" | | The file exists but can't be read | The original file system error (EACCES, EISDIR…) |

When a callback throws, the original error is available in error.cause. The raw value is never included in the messages, since it may be a secret.

Because nothing is validated up front, a missing required variable is only reported when it's read. To fail at startup, read the variables you need while your application boots.

API

new Env(path, options)

| Parameter | Type | Description | | ------------------- | -------------- | ---------------------------------------------------- | | path | string | Path to the .env file. | | options.variables | EnvVariables | The variables that get can read. | | options.cacheable | boolean | Read the file only once. Defaults to false. |

env.get(name)

Returns the value of the variable declared as name, following the rules above.

env.path

The path given to the constructor, as is.

Exported types

| Type | Description | | --------------------- | ------------------------------------------------------------------ | | EnvOptions | The constructor options. | | EnvVariables | The variables option. Use it with satisfies. | | EnvVariable | EnvOptionalVariable \| EnvRequiredVariable. | | EnvOptionalVariable | A variable without required: true. | | EnvRequiredVariable | A variable with required: true. | | EnvValue<V> | The type returned by get for the variable V. |

License

MIT